Errors

Error format

Prism returns an OpenAI-compatible error envelope:

{
  "error": {
    "message": "The requested model does not exist.",
    "code": "model_not_found"
  }
}

Anthropic Messages clients receive the corresponding Anthropic error shape. Use the HTTP status as the primary retry signal.

Status codes

Status	Meaning	Retry
`400`	The body, parameter, message sequence, or model ID is invalid.	No. Correct the request first.
`401`	The API key is missing, invalid, expired, or revoked.	No. Correct the credential first.
`403`	The key cannot access the requested model or operation.	No. Change access or the request.
`404`	The endpoint or model was not found.	No. Check the URL and model ID.
`408`	The server timed out while receiving the request.	Yes, if the operation is safe to repeat.
`413`	The request body or model context is too large.	No. Reduce the input.
`422`	The body is well-formed but cannot be processed.	No. Correct the input.
`429`	A request or token rate limit was exceeded.	Yes, after `Retry-After`.
`500`	Prism encountered an unexpected internal error.	Yes, with backoff.
`502`	An upstream inference worker returned an invalid response.	Yes, with backoff.
`503`	Inference capacity is temporarily unavailable.	Yes, with backoff.
`504`	An upstream inference request timed out.	Yes, with backoff.

Rate limits

For 429, wait for the Retry-After delay when present. If the header is missing, use exponential backoff with jitter.

const delay = (attempt: number, retryAfter: string | null): number => {
  if (retryAfter != null) {
    const seconds = Number(retryAfter);
    if (Number.isFinite(seconds)) {
      return Math.max(0, seconds * 1000);
    }
  }

  const exponential = Math.min(30_000, 500 * 2 ** attempt);
  return Math.random() * exponential;
};

Immediate retries add load and usually fail again. Cap the number of attempts and surface the final error to the caller.

Retry policy

Retry 408, 429, 500, 502, 503, and 504 when the request is safe to repeat. Do not retry other 4xx responses until you change the request or credential. For streaming requests, distinguish between:

A connection that failed before any content was consumed. Retrying is usually safe.
A connection that failed after partial content was consumed. Treat the partial generation as interrupted or begin a new turn. Do not silently append a retry to it.

Common fixes

Error	Check
`model_not_found`	Use an ID from the model catalog.
`context_length_exceeded`	Remove old turns, reduce attached context, or choose a larger-context model.
`invalid_api_key`	Confirm the key is loaded server-side and the authorization header is present.
`invalid_request_error`	Check required fields, message roles, tool schemas, and `response_format`.
`rate_limit_exceeded`	Honor `Retry-After`, reduce concurrency, and add jittered backoff.

Log the request ID from response headers when reporting a persistent server error. Never log the API key or full prompts containing secrets.

Get started

API reference

Guides

Resources

Error format

Status codes

Rate limits

Retry policy

Common fixes

​Error format

​Status codes

​Rate limits

​Retry policy

​Common fixes

Error format

Status codes

Rate limits

Retry policy

Common fixes