Errors

Handle Prism inference errors, rate limits, timeouts, and retries.

Error format

Prism returns an OpenAI-compatible error envelope:

{
  "error": {
    "message": "The requested model does not exist.",
    "code": "model_not_found",
    "retryable": false,
    "fix": "Fetch GET https://api.prisminference.com/v1/models and use an id returned by the live catalog.",
    "docs_url": "https://docs.prisminference.com/errors"
  }
}

Agents should use retryable as the primary retry signal, follow fix, and respect Retry-After. Do not retry an unchanged request when retryable is false.

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.
402	The workspace has insufficient prepaid credit.	No. Ask the human to add credit.
403	The organization cannot access the requested model.	No. Contact Prism to request access.
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	The API key was rate-limited, or the model is at capacity.	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

When a key is rate-limited, the API returns 429 with Retry-After. Retry after that interval. The header is seconds; the example below is a response shape, not a published quota.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "error": {
    "message": "API key rate limit exceeded.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded",
    "retryable": true,
    "fix": "Wait for the Retry-After interval, then retry with bounded exponential backoff.",
    "docs_url": "https://docs.prisminference.com/errors"
  }
}

If Retry-After is missing, use exponential backoff with jitter. Immediate retries add load and usually fail again. Cap the number of attempts and surface the final error to the caller.

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;
};

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 source, or ask the workspace owner for a Prism API key.
invalid_request_error	Check required fields, message roles, tool schemas, and response_format.
rate_limit_exceeded	Honor Retry-After, then retry.

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