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/dashboard/settings |
| 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 |
| 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