Error reference

Standardized error format and the most common codes.

Format

Every error follows the same JSON structure, regardless of the endpoint:

json

{
  "error": {
    "code": "insufficient_credits",
    "message": "Solde de credits insuffisant ou budget mensuel du projet depasse.",
    "request_id": "9480fe92-f68e-4731-b98e-d35a5e8b9819",
    "details": {}
  }
}

request_id identifies the request end-to-end across services — useful to provide if you contact us about an unexpected error.

Common codes

HTTP	code	Meaning
401	missing_api_key	Missing Authorization header.
401	invalid_api_key	Invalid, revoked, or expired API key.
403	insufficient_scope	The key does not have the required scope for this category.
403	not_a_member	You do not belong to this organization.
403	csrf_check_failed	Missing security header (session cookie, not applicable to API key usage).
404	model_not_found	routing_strategy "manual" with a model unknown to the catalog.
404	no_model_available	No model matches the requested criteria.
402	insufficient_credits	Insufficient credit balance or the project's monthly budget was exceeded.
409	conflict	State incompatible with the action (e.g. agent conversation not idle).
422	validation_error	Invalid request body (missing field, wrong type...).
429	rate_limit_exceeded	Too many requests for this key — see Rate limits.
503	all_providers_unavailable	All candidate providers failed (see Routing & fallback).

In the SDKs

The official SDKs convert each HTTP status range into a typed error class (AuthenticationError, PermissionDeniedError, NotFoundError, InsufficientCreditsError, ConflictError, ValidationError, RateLimitError, ServerError), all exposing .code, .status, .requestId and .details in addition to the message. See JavaScript SDK / Python SDK.