# Errors (/en/docs/api/errors) When something fails, the HTTP status code tells you the class of the failure; the body gives the specific cause in the format of that prefix; and every error response also carries four `x-praxis-problem-*` headers plus one `x-praxis-recovery-action`, so retry logic only needs the headers, whatever the body looks like. ## Status codes [#status-codes] | Status | Meaning | What to do | | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------- | | `400` | Invalid request fields or format | Correct the parameters; do not retry unchanged | | `401` | Missing or invalid credentials | Check your API key | | `402` | Insufficient balance or paid allowance | Add funds or contact your account administrator | | `403` | Access denied | Check key permissions and resource ownership; contact support if needed | | `404` | Resource, model or route not found | Check the ID, model name and path | | `408` | Request timed out | Check connectivity before retrying; verify whether writes completed first | | `409` | Resource state or concurrent update conflict | Read the current state and adjust the request | | `413` | Payload or file too large | Reduce the payload or use a URL input supported by the endpoint | | `422` | Request content cannot be processed | Correct parameters or input using the error details | | `429` | Rate, concurrency or model quota exceeded | Honor retry-after; let in-flight requests finish when concurrency is full | | `500` | Internal platform error | Retry later; contact support with X-Request-Id if it persists | | `501` | Capability not implemented | Use a supported endpoint; do not retry | | `502` | Upstream call failed or returned an invalid response | Back off and retry; switch models or contact support if it persists | | `503` | Service or eligible route temporarily unavailable | Back off and retry, or select another model | | `504` | Upstream response timed out | Back off and retry; check write results first to avoid duplicate creation | ## Error codes [#error-codes] These are common machine-readable codes, not an exhaustive enum for every endpoint. Compatible error bodies may use protocol-specific code/type values. For cross-protocol handling, read `x-praxis-problem-code`, which can differ from the body code. Codes are case-sensitive. | code | When it occurs and what to do | | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AUTHENTICATION_ERROR` | The key is missing or invalid; check or replace your credentials. | | `VALIDATION_ERROR` | A parameter violates a format, type or range requirement; correct it using the details. | | `INPUT_NOT_REPRESENTABLE` | The selected model or protocol cannot represent an input option; remove the option or switch models. | | `NOT_FOUND` | The resource is absent or not visible to this account; check the ID and account. | | `MODEL_NOT_FOUND` | The model is absent or not visible; select an available name from the model list. | | `MODEL_PROTOCOL_NOT_OFFERED` | The model does not offer this protocol; use a supported endpoint or another model. | | `MODEL_PROTOCOL_LINE_UNAVAILABLE` | Qualified routes for the protocol are unavailable; back off and retry or switch models. | | `GENERATION_NOT_FOUND` | The generation is absent or belongs to another account; check the generation ID from the response headers and the key. | | `RATE_LIMITED` | A rate or concurrency limit was exceeded; honor retry-after and reduce rate or concurrency. | | `UPSTREAM_ERROR` | The upstream call failed or returned an invalid response; retry with backoff when retryable, then switch models or contact support if it persists. | | `PROVIDER_SELECTION_NOT_ALLOWED` | Provider order/only was supplied without BYOK; remove provider selection or provide your own upstream key. | | `not_implemented` | The endpoint or capability is not implemented; use a supported capability instead of retrying. | | `model_protocol_not_offered` | HTTP 404: the model does not declare the requested protocol. Check `supported_apis` in `GET /model/v1/models` and use the corresponding endpoint. For Google models, use `/google/v1beta/models/{model}:generateContent` with a Google request body; changing only the prefix is insufficient. | | `provider_unavailable` | HTTP 502: all available routes for this request failed. Retry with backoff; if failures persist, switch models and contact support with `X-Request-Id`. | | `thinking_disable_unsupported` | HTTP 400: thinking cannot be disabled, for example `reasoning_effort="none"` on `glm-5.3`. Omit the disabling setting or choose a supported effort level; switch models if you need thinking disabled. | | `insufficient_quota` / `INSUFFICIENT_BALANCE` | HTTP 402: insufficient balance; body or header codes vary by endpoint. Add funds or contact your account administrator before retrying; avoid immediate retry loops. | | `validation_error` (`response_format`) | HTTP 400, for example: `Model "deepseek-flash" does not support json_schema on this API.` Switch to a model supporting `json_schema` on this endpoint. If valid JSON alone is sufficient, use `json_object`; it does not enforce a schema. | | `validation_error` (named parameter) | HTTP 400: with `provider.require_parameters=true`, the model may reject a requested parameter. For example, `param: "logprobs"` accompanies `does not support the requested logprobs value`. Adjust the named parameter or switch models. Disabling the check does not prove the parameter takes effect. | ## Error body [#error-body] The body format follows the first segment of the address, same as success responses — your SDK needs no special handling for errors. **Vendor prefixes** (`/openai` `/anthropic` `/google` `/e2b` `/tavily`): identical to that vendor's official API error body. ```json // /openai { "error": { "code": 401, "message": "Invalid API key." } } ``` ```json // /anthropic { "type": "error", "error": { "type": "authentication_error", "message": "Invalid API key." } } ``` **Praxis prefixes** (`/agent` `/model` `/sandbox` `/search` `/meta`): standard Problem Details (RFC 9457), `Content-Type: application/problem+json`. ```json { "type": "https://deepraxis.ai/problems/authentication_error", "title": "authentication_error", "status": 401, "detail": "Invalid API key.", "instance": "problem_eqfnxu", "code": "AUTHENTICATION_ERROR", "retryable": false } ``` | Field | Meaning | | ------------------ | --------------------------------------------------- | | `type` | URL of the error type, stable, safe to branch on | | `title` / `detail` | Human-readable summary and specific cause | | `status` | Same as the HTTP status code | | `instance` | ID of this error, attach it when contacting support | | `code` | Machine-readable error code | | `retryable` | Whether retrying verbatim might succeed | ## Error headers (five common + one rate-limit header) [#error-headers-five-common--one-rate-limit-header] The five common headers are independent of body format; the sixth, scope, applies to rate-limit errors: | Header | Meaning | Example | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `x-praxis-problem-code` | Cross-protocol classification; may differ from the body's `code` | `AUTHENTICATION_ERROR` | | `x-praxis-problem-kind` | Broad class — what broke | `authentication_failure` | | `x-praxis-problem-origin` | Who owns it — who can fix it: `user` (your request or credential), `platform` (us), `upstream_provider` (the vendor), etc. | `unknown` | | `x-praxis-problem-retryable` | Whether retrying verbatim might succeed | `false` | | `x-praxis-problem-scope` | Rate-limit layer, when applicable: platform or model | `platform` | | `x-praxis-recovery-action` | Suggested action | `relogin` | ## Retrying [#retrying] * `retryable` is `true` (or status `429` `502` `503`): retry with exponential backoff; for `429` honor `retry-after` first. * Everything else: never retry verbatim — fix the request or the Key first.