# Errors HTTP status codes, error envelopes on each API, and retry guidance. The API returns standard HTTP status codes. Error bodies use OpenAI's format, except on the [Messages API](https://docs.privatemind.com/messages-api.html), which uses Anthropic's (see [Messages API](https://docs.privatemind.com/errors.html#messages-api) below): ```json { "error": { "message": "Human-readable description", "type": "", "code": "" } } ``` The [Model servers API](https://docs.privatemind.com/model-servers-api.html#errors), the [Workspaces API](https://docs.privatemind.com/workspaces-api.html#errors) and the [Kubernetes API](https://docs.privatemind.com/kubernetes-api.html#errors) have their own error formats. ## Common status codes | Code | Meaning | What to do | | --- | --- | --- | | `200` | Success | - | | `400` | Bad request: malformed JSON, unknown field, value out of range, exceeds context window | Fix the request; check `supported_parameters` for the model | | `401` | Authentication failed: key missing, malformed, revoked, or expired | Check the `Authorization` header, or create a new key | | `402` | Budget exhausted: your key or org spend has reached its cap | Raise the key cap on the **API Keys** page, or ask your org admin | | `403` | Forbidden: the key may not call this endpoint, your org has no access to this external provider model, or the request came from an IP address your [IP rules](https://docs.privatemind.com/api-keys.html#restricting-keys-by-ip-address) don't allow | Call from an allowed address, or ask your org admin for access | | `404` | Unknown endpoint, or a model id that doesn't exist or that your org can't use | Check the path; check `/v1/models` | | `413` | Payload too large: the body is over the endpoint's cap (64 MB for chat completions and file uploads, 32 MB for the Responses API, 75 MB for audio uploads, 10 MB for most other endpoints) | Shorten or split | | `429` | Rate limited: too many requests per minute on this key | Back off with exponential delay | | `5xx` | Server error: timeout, memory limit, transient failure | Retry with exponential backoff; switch model if it persists | ## Retry strategy Retry `429` and `5xx`. Don't retry other `4xx` codes: they'll fail the same way. - Use exponential backoff with jitter, starting at about 1s and capped at about 30s. - Stop after 3 to 5 retries and surface the final error. - For `429`, send fewer requests at once on each key, or spread them across keys. ## Streaming errors An error **before** the stream starts returns a normal JSON error body with the matching status code. An error **mid-stream** arrives as an SSE chunk with an `error` field when the API can still send one: ```text data: {"id": "chatcmpl-...", "object": "chat.completion.chunk", "model": "...", "choices": [], "error": {"message": "...", "type": "server_error", "code": "provider_stream_failed"}} ``` Don't use `[DONE]` to tell success from failure. An error chunk can be followed by `[DONE]`, and if the connection to the model drops, the stream can end with neither. Check each chunk for `error`, and treat a stream that ends without a `finish_reason` as incomplete. A cut stream can also end with `finish_reason: "length"` and `[DONE]` and no error. So a `length` finish means the answer stopped early, either at your token limit or because the stream was cut. > [!TIP] > Base retry and branching logic on `error.code`, the stable field, and on `error.type`. `error.message` is written for people and may change between releases. ### Error codes | Code | Meaning | | --- | --- | | `budget_exceeded` | Key or org budget is exhausted | | `rate_limit_exceeded` | Too many requests per minute | | `timeout` | Model didn't respond in time (mid-stream chunks; see above) | | `context_length_exceeded` | The prompt does not fit the model's context window together with `max_output_tokens`, on the [Responses API](https://docs.privatemind.com/errors.html#responses-api) | ### Errors relayed from the model When the model itself rejects a request, most often because the prompt is longer than the context window, the API passes the model's error through unchanged. Then **`code` is the HTTP status as a number, not one of the strings above**, and `type` is the model's own: ```json { "error": { "message": "This model's maximum context length is 262144 tokens. However, you requested 4 output tokens and your prompt contains at least 262141 input tokens...", "type": "BadRequestError", "param": "input_tokens", "code": 400 } } ``` For these errors, branch on the HTTP status, and check the type of `code` before you treat it as a string. The Responses API rewrites a context overflow as `context_length_exceeded`: see [Responses API](https://docs.privatemind.com/errors.html#responses-api). ## Messages API Requests to `/v1/messages*`, and any request with an `anthropic-version` header, get errors in Anthropic's format, so the Anthropic SDKs raise their usual typed exceptions: ```json { "type": "error", "error": { "type": "rate_limit_error", "message": "Human-readable description" }, "request_id": "6f5c..." } ``` The same id is in the `request-id` response header. | Status | `error.type` | Meaning | Retry? | | --- | --- | --- | --- | | `400` | `invalid_request_error` | Malformed request, missing `max_tokens`, unsupported content such as a PDF | No | | `401` | `authentication_error` | Key missing, malformed, revoked, or expired | No | | `402` | `billing_error` | Key or org budget exhausted | No | | `403` | `permission_error` | The key may not use this endpoint or external provider model, or the request came from an IP address the [IP rules](https://docs.privatemind.com/api-keys.html#restricting-keys-by-ip-address) don't allow | No | | `404` | `not_found_error` | Unknown model or one your org can't use, or an unknown file, batch, or path | No | | `409` | `conflict_error` | The object is not in a state that allows this, such as results of a running batch | No | | `413` | `request_too_large` | Body over 32 MB (64 MB to create a message batch) | No | | `429` | `rate_limit_error` | Too many requests per minute; `retry-after` says how long to wait | Yes | | `500` | `api_error` | Unexpected server error | Yes | | `504` | `timeout_error` | The model did not answer in time | Yes | | `529` | `overloaded_error` | Capacity is full right now | Yes | A prompt longer than the model's context window returns `400` with a message that starts `prompt is too long`. Clients such as Claude Code look for that wording to compact a conversation. Mid-stream, an error arrives as an `error` event, and the stream closes without a `message_delta`, so a cut-off answer never looks complete: ```text event: error data: {"type":"error","error":{"type":"api_error","message":"the model stream ended before the turn finished"}} ``` The same event, with the message `the model stream interleaved a tool call with other output`, ends a stream if the model goes back to a tool call after starting other output. That call's `tool_use` block has already stopped with only part of its input. Don't run it: retry the request. The Anthropic SDKs retry `408`, `409`, `429`, `5xx` and `529` on their own, with backoff. Retrying can't fix a `409`, so for that code the SDK's retries only delay the error. ## Responses API Requests to `/v1/responses` get errors in OpenAI's format, with the status codes above. Anything the endpoint refuses, such as `previous_response_id`, custom tools or file input, returns `400` with `type` `invalid_request_error` and a message saying what to send instead. See [Responses API → Errors](https://docs.privatemind.com/responses-api.html#errors). A prompt that does not fit the model's context window together with `max_output_tokens` returns `400` with `code` `context_length_exceeded`. Responses clients look for that code to compact a conversation: ```json { "error": { "code": "context_length_exceeded", "message": "This model's maximum context length is 262144 tokens. However, you requested 262000 output tokens and your prompt contains at least 145 input tokens, ...", "param": null, "type": "invalid_request_error" } } ``` A `429` with `type` `server_capacity` and `code` `too_many_requests` means too much is in flight for the key. With tools and a `text.format` on the request, it can also mean your organization or the whole service has too much in flight. Such a request's final answer may have to be generated again: see [With tools on offer](https://docs.privatemind.com/responses-api.html#with-tools-on-offer). Nothing ran, unless the refused request was the second pass of an answer being generated again. Retry after the 60 seconds in the `retry-after` header. Mid-stream, an error arrives as a `response.failed` event, and the stream closes without `response.completed`. The event's response has `status: "failed"` and an `error` with a `code` and a `message`. A context overflow on a stream arrives this way too, with `code` `context_length_exceeded` and HTTP status `200`: ```text event: response.failed data: {"type":"response.failed","sequence_number":2,"response":{"id":"resp_05d3e0e0ca7f4621bc90251310cf3bad","object":"response","status":"failed","error":{"code":"context_length_exceeded","message":"This model's maximum context length is 262144 tokens. ..."},...}} ``` ## When a request looks stuck - Most often, a proxy between you and the API is buffering a streamed response. See [Streaming](https://docs.privatemind.com/streaming.html). - Otherwise, check the model's status. A model in maintenance is dropped from `GET /v1/models`. ## Where next - [Rate limits](https://docs.privatemind.com/rate-limits.html) for the `402` and `429` thresholds your key inherits. - [Authentication](https://docs.privatemind.com/authentication.html) for what `401` means and how to rotate. - [Streaming](https://docs.privatemind.com/streaming.html) for how errors surface mid-response.