What error codes does the LLM gateway return, and how do I handle them?
All error codes returned by the Cognocient AI proxy. Every 4xx/5xx includes a structured JSON body with error type, message, and context.
Every error from the Cognocient AI proxy includes a structured JSON body with an error type, message, and context. This reference covers all 4xx and 5xx codes — including budget-specific errors your application should handle gracefully.
Error codes
| Status | Error field | Meaning | Fix |
|---|---|---|---|
| 401 | type: invalid_request_error | Proxy key not found or malformed | Verify key starts with sk-cog- and was generated in Settings → Proxy Keys |
| 402 | code: trial_expired | 10-day trial ended, no active plan (dashboard/API endpoints only — see note below) | Upgrade at cognocient.com/settings?tab=billing |
| 402 | type: provider_quota_exhausted | Your provider said this API key's spend limit or credit balance is used up, so calls on the key are held for up to 10 minutes instead of being sent (chat, /v1/messages, embeddings, images, audio, rerank). retry_after_seconds and Retry-After say when the next check call goes through; provider_message is the provider's own text. See the spend-cap circuit | Raise the limit or add credits in the provider's console; calls resume on their own |
| 429 | type: failure_loop_detected | Failure Loop Breaker in kill mode stopped a stuck agent session; reason says which signal | Change the agent's approach, or raise a polling tool's threshold under Monitor → Loop Breaker |
| 429 | type: budget_error | Block budget exhausted (and its fallback allowance, if it has one) | Increase budget in Dashboard → Budgets, add a fallback allowance, or use Degrade mode to downgrade gracefully |
| 429 | type: run_budget_exceeded | Per-run agent budget hit | Increase the run budget's per-run limit |
| 429 | type: velocity_limit_exceeded | Token-per-minute circuit breaker tripped | Reduce request frequency or set a manual TPM limit in Settings → Proxy Keys → Velocity Limit |
| 429 | type: dollar_velocity_limit_exceeded | Dollar velocity breaker tripped (per minute, burst, one model price tier, then model_tier is set, or one agent run, then run_id is set and only that run is blocked); reason says which. With the spend fuse on (the default), the key stays blocked for the fuse duration and fuse_tripped is true | Wait for Retry-After, or stop the loop and reset the fuse in Settings → Safety & Limits → Velocity Limit. Raise or set limits in the same place |
| 429 | type: concurrency_limit_exceeded | Too many calls in flight at once on the key, or within one run (scope says which, run_id is set for a run). See concurrency limits | Retry after Retry-After (1 second), lower your parallelism, or raise the limit in Settings → Safety & Limits → Velocity Limit |
| 400 | type: guardrail_moderation_blocked | Moderation in block mode flagged the newest user message; categories lists why. code is content_filter | Change the prompt, or set moderation to alert |
| 200 | finish_reason: content_filter | A response guardrail withheld the answer (the response header x-cog-guardrail says which). The call was billed | Check the guardrail events, or switch the response check to alert or redact |
| 502 | type: secret_manager_error | Your provider key is a secret-manager reference and the manager could not be reached, refused the request, or the secret is missing | Check the connection on the Integrations page; the message names the manager. Cognocient AI never falls back to another key |
| 403 | code: plan_required | The feature (for example the Batch API, MCP gateway, SCIM or JWT authentication) is not on your plan | Upgrade the plan named in the response |
| 200 | JSON-RPC error.code: -32001 / -32002 | MCP gateway: a tool call was refused by the server's tool policy (-32001) or blocked for sensitive arguments (-32002). The HTTP status is 200 because the error is in the JSON-RPC body | Allow the tool in the server's policy, or remove the sensitive data from the arguments |
| any | Anthropic-format {"type":"error","error":{...}} | Returned by the Anthropic Messages endpoint (/v1/messages, used by Claude Code and the Anthropic SDK). Our own refusals use this shape too; budget, freeze, plan and auth refusals carry x-should-retry: false so clients don't retry them. Errors from Anthropic are passed through unchanged | As for the matching row in this table |
| 403 | type: account_frozen | Emergency Freeze is active for this account | Unfreeze from Settings → Safety & Limits, or the banner shown across the dashboard |
| 503 | (no type field, message only) | AI provider returned an error, or Cognocient AI couldn't reach it | Check the provider status page. The error body includes an upstream-unavailable message. |
| 504 | (no type field, message only) | AI provider took too long to respond | Retry with exponential backoff. For long-running tasks, consider the batch API. If the response has x-cog-billing-outcome: unknown, the provider may have billed the call, so its estimate was charged to your budgets (see Budgets → Timeouts). |
| 409 | type: idempotent_request_in_flight | A request with the same X-Idempotency-Key was still running after a 30-second wait (non-streaming retries are held and given the original's result), or is a stream | Wait for it (the response has Retry-After) and retry: a finished request's result is replayed |
All error responses include a Content-Type: application/json header and a body of the form: {"error":{"message":"...", "type":"..."}} — except the 402 trial-expired response, which uses "code" instead of "type", and the 503/504 provider-passthrough errors, which carry only "message" with no type field at all. Catch errors by status code first, and check for error.type or error.code where present rather than assuming one is always there.
The 402 trial-expired check only gates dashboard and analytics API endpoints today — it is not enforced on the proxy's chat-completion path itself. A trial that has ended does not currently block AI calls made through the proxy.
Response headers
Every proxy response includes these headers. Read them to detect degraded calls, cache hits, and cost attribution.
x-cog-degraded (e.g. true)
Call was downgraded to a cheaper model due to budget threshold.
x-cog-original-model (e.g. gpt-4o)
Model that was requested in the original call.
x-cog-degraded-model (e.g. gpt-4o-mini)
Model that was actually used after degradation.
x-cog-cache-hit (e.g. true)
Response was served from similarity cache — cost was $0.00.
x-cog-similarity-score (e.g. 0.97)
Similarity score of the cached response (1.0 = exact match).
x-cog-max-tokens-shrunk (e.g. 812)
The call was near a Block budget's limit and you sent X-Cog-Shrink-To-Fit: true, so its output limit was lowered to this to fit. x-cog-max-tokens-original has the value you sent.
x-cog-run-limit-usd, x-cog-run-committed-usd, x-cog-run-remaining-usd
On calls with X-Cost-Run-ID: the run's ceiling, what it has committed so far (including this call's reservation), and what's left.
x-cog-billing-outcome (unknown)
On a 504 after the provider received the call: it may have been billed, so its estimate was charged.
x-cog-idempotent-replay, x-cog-idempotent-waited (true)
The response is the stored result of an earlier request with the same X-Idempotency-Key. waited means this request arrived while the original was still running and was held until it finished.
Related articles