Errors & Status Codes
Errors come back in one closed shape, with a code you can branch on and a request id you can quote to support.
Inference endpoints return the OpenAI-compatible envelope:
{
"error": {
"message": "Invalid or missing API key",
"type": "invalid_request_error",
"code": "invalid_api_key",
"request_id": "req_01J8…"
}
}The dashboard/account API uses the same idea in a slightly different envelope, and never leaks stack traces or internals:
{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits for this request.",
"requestId": "01J8…"
}
}Status codes
400
invalid_request / malformed_tools
Body failed validation — unknown params, malformed tool definitions, missing model or messages.
401
invalid_api_key
Key missing, mistyped or revoked. Check the Authorization header.
402
insufficient_credits
The account balance cannot cover the request. Top up in the dashboard.
403
model_not_allowed / ip_not_allowed
The key's scope (model allowlist, IP list) rejects this request.
404
model_not_found
The model id is not in the live catalogue — refetch /v1/models.
429
rate_limit_error / spend_cap_exceeded / token_quota_exceeded
Per-key RPM or RPD exhausted, spend cap hit, or an IP lockout after repeated failures. Honour Retry-After.
5xx
upstream_error
The provider failed after retries. Safe to retry with backoff; the request id identifies it in logs.