Error Codes

Standard error responses across all Zihin API endpoints.

Error Format

{
  error: string;      // Error code
  message: string;    // Human-readable description
  status: "error";
  details?: object;   // Additional context (optional)
}

Authentication Errors

Code	HTTP Status	Description
authentication_required	401	No authentication provided
invalid_api_key	401	API key is invalid or expired
invalid_token	401	JWT token is invalid or expired
insufficient_permissions	403	User lacks required role

Rate Limiting Errors

Code	HTTP Status	Description
rate_limit_exceeded	429	Too many requests
quota_exceeded	429	Monthly/daily quota reached
token_limit_exceeded	429	Token pack exhausted

Request Errors

Code	HTTP Status	Description
invalid_request	400	Malformed request body
model_not_found	400	Specified model doesn't exist
agent_not_found	404	Agent ID not found
tenant_not_found	404	Tenant ID not found

Provider Errors

Code	HTTP Status	Description
provider_error	502	LLM provider returned an error
provider_timeout	504	LLM provider didn't respond in time
provider_unavailable	503	LLM provider is down

Handling Errors

# Example error response
HTTP/1.1 401 Unauthorized
{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired",
  "status": "error"
}

For 429 errors, check the Retry-After header for when to retry.