Reference

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

StatusError fieldMeaningFix
401type: invalid_request_errorProxy key not found or malformedVerify key starts with sk-cog- and was generated in Settings → Proxy Keys
402code: trial_expired10-day trial ended, no active plan (dashboard/API endpoints only — see note below)Upgrade at cognocient.com/settings?tab=billing
402type: provider_quota_exhaustedYour 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 circuitRaise the limit or add credits in the provider's console; calls resume on their own
429type: failure_loop_detectedFailure Loop Breaker in kill mode stopped a stuck agent session; reason says which signalChange the agent's approach, or raise a polling tool's threshold under Monitor → Loop Breaker
429type: budget_errorBlock 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
429type: run_budget_exceededPer-run agent budget hitIncrease the run budget's per-run limit
429type: velocity_limit_exceededToken-per-minute circuit breaker trippedReduce request frequency or set a manual TPM limit in Settings → Proxy Keys → Velocity Limit
429type: dollar_velocity_limit_exceededDollar 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 trueWait 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
429type: concurrency_limit_exceededToo 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 limitsRetry after Retry-After (1 second), lower your parallelism, or raise the limit in Settings → Safety & Limits → Velocity Limit
400type: guardrail_moderation_blockedModeration in block mode flagged the newest user message; categories lists why. code is content_filterChange the prompt, or set moderation to alert
200finish_reason: content_filterA response guardrail withheld the answer (the response header x-cog-guardrail says which). The call was billedCheck the guardrail events, or switch the response check to alert or redact
502type: secret_manager_errorYour provider key is a secret-manager reference and the manager could not be reached, refused the request, or the secret is missingCheck the connection on the Integrations page; the message names the manager. Cognocient AI never falls back to another key
403code: plan_requiredThe feature (for example the Batch API, MCP gateway, SCIM or JWT authentication) is not on your planUpgrade the plan named in the response
200JSON-RPC error.code: -32001 / -32002MCP 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 bodyAllow the tool in the server's policy, or remove the sensitive data from the arguments
anyAnthropic-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 unchangedAs for the matching row in this table
403type: account_frozenEmergency Freeze is active for this accountUnfreeze 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 itCheck the provider status page. The error body includes an upstream-unavailable message.
504(no type field, message only)AI provider took too long to respondRetry 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).
409type: idempotent_request_in_flightA 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 streamWait 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.

On this page