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 type | Meaning | Fix |
|---|---|---|---|
| 401 | invalid_proxy_key | Proxy key not found or malformed | Verify key starts with sk-cog- and was generated in Dashboard → API Keys |
| 402 | trial_expired | 10-day trial ended, no active plan | Upgrade at cognocient.com/dashboard/billing |
| 429 | budget_exceeded | Monthly feature budget exhausted | Increase budget in Dashboard → Budgets, or enable Degrade mode to downgrade gracefully |
| 429 | run_budget_exceeded | Per-run agent budget hit | Increase per_run_limit_usd on the budget, or pass a higher limit via X-Cost-Run-Budget header |
| 429 | velocity_exceeded | Token/minute or requests/minute rate limit hit | Reduce request frequency or increase velocity limit in Dashboard → Budgets → Guardrails |
| 500 | provider_error | AI provider returned an error | Check the provider status page. The error body will include the upstream error message. |
| 504 | provider_timeout | AI provider took > 60 seconds | 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":"..."}}. Catch errors by error.type, not by message string.
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).
Next steps: Troubleshooting · Budget Enforcement · Guardrails
Related articles