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 — but only when enabled. Input blocks require Project > Security > Enable security scanning; output blocks additionally require a governance policy or active custom data rule. With everything off (default), PII and injections return 200 OK unmodified.

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.
• byok_required (402) — the project has no active BYOK key for the auto task (chat, embeddings, images, or speech). Add the provider key in Project > Providers; the error message lists the available BYOK providers. An image prompt with only text-model keys 402s the same way.
• budget_exceeded (402) — the call overspent its per-request max_cost_usd. Lower the budget pressure (smaller max_tokens, cheaper model) or raise the budget; agent loops should stop on this code, not retry into it.
• rate_limit_exceeded (429) — 60 requests/min per project for all tiers. Back off for Retry-After seconds or use a second project.
• provider_error (400) — read the message; the truncated upstream body is included.