Error Reference

Every AI Gateway endpoint (chat, vision, audio, embeddings, …) returns errors as flat JSON. The error field is always present and is a string — for gateway-level failures it is a human-readable phrase (with a machine code in code), while endpoint-level failures use the machine code directly as error (e.g. "bad_request").

{
  "error": "Error message describing what went wrong",
  "message": "Human-readable details",
  "code": "machine_code"
}

Fields by failure class:

The error envelope is not OpenAI's { "error": { "message", "code", "type" } } shape. Parse error as a string.

These come from the shared gateway middleware before the endpoint runs:

The AI endpoints return these via error (and code where meaningful):

Security guards (input/output) return their own blocked responses with error, message, and reasons in the 4xx range.

Rate-limited responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix timestamp in milliseconds), and every gateway response carries X-Request-Id for correlation.

429 responses also set a standards-compliant Retry-After header in seconds. The same value is available as retry_after_ms in the body.

try {
  const response = await cencori.ai.chat({ model: 'gpt-4o', messages });
} catch (error: any) {
  if (error.status === 429) {
    const retryAfter = error.retryAfterMs ?? 60_000;
    // Wait and retry...
  }
}

• credit_balance_exhausted (403) — top up in Organization → Billing. Free/Enterprise tiers aren't credit-gated.
• rate_limit_exceeded (429) — 60 requests/min per project for all tiers. Back off for Retry-After seconds or use a second project.
• monthly_request_limit_reached (429) — free tier resets on the monthly cycle (see reset-usage cron).
• provider_error (400) — read the message; the truncated upstream body is included.