Errors

HTTP status codes the API returns and how to respond to each.

Errors follow the OpenAI-compatible shape: an HTTP status plus a JSON body with an error object.

{
  "error": {
    "message": "key not allowed to access model. Tried to access primalabs-ai/does-not-exist",
    "type": "key_model_access_denied",
    "param": "model",
    "code": "403"
  }
}

Status codes

Status	Meaning	What to do
400	Bad request — malformed JSON, missing or invalid parameters.	Fix the request; do not retry unchanged.
401	Missing or invalid API key.	Check the Authorization header and the key.
403	The key cannot access this model — including model IDs that do not exist.	Check the model against GET /models.
404	Unknown route.	Check the URL path against the endpoint list.
429	Rate limited — one of the three limits tripped.	Back off and retry with jitter; honor Retry-After.
500	Unexpected server error.	Retry with backoff; if it persists, contact support.
502	Upstream error reaching the model.	Retry with backoff.
503	No healthy capacity for the model right now.	Retry shortly; check the status page.

A typo in the model ID returns 403, not 404 — the API answers in terms of what your key may access, so an unknown model and a model you are not entitled to look the same.

Retry guidance

• Retryable: 429, 500, 502, 503 — use exponential backoff with jitter.
• Not retryable as-is: 400, 401, 403, 404 — the request or credentials must change first; retrying unchanged will fail the same way.

The message field is meant for logs and debugging, not for pattern-matching in code. Branch on the HTTP status, which is stable, rather than on the message text.