What error codes does the Cognocient proxy return?
All error codes returned by the Cognocient proxy. Every 4xx/5xx includes a structured JSON body with error type, message, and context.
Every error from the Cognocient 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 |
| 429 | type: budget_error | Monthly feature budget exhausted | Increase budget in Dashboard → Budgets, or enable 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-per-minute circuit breaker tripped — see Guardrails → Dollar-denominated velocity | Reduce request frequency or set a manual $/min limit in Settings → Proxy Keys → Velocity Limit |
| 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 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 |
| 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 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. |
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).
Related articles