Error body shape
message is safe to surface to developers. type is machine-readable and useful for branching client-side. When the gateway returns OpenAI-style metadata, SDK errors preserve code and param as separate fields, for example unsupported_parameter and dimensions.
Status code reference
200 Success
Normal. Read the response body.400 Bad Request
Malformed request. Check JSON shape, required fields, and content type. Do not retry. Fix the request. Model and backend safety checks also return 400 when RunInfra can identify a configuration problem before retrying would help:error.code | What it means | Recovery |
|---|---|---|
unsupported_backend_modality | The selected backend cannot serve the requested model family or modality. | Choose one of the compatible backends shown in the dashboard, or deploy with automatic backend selection. |
hf_model_access_required | The selected Hugging Face model requires accepted terms, repository access, or a configured token. | Accept the model terms in Hugging Face and configure a token with access before retrying. |
remote_code_approval_required | The model requires custom remote code before it can load safely. | Review the model repository and enable trusted remote code only when you accept that code path. |
401 Unauthorized
Missing or invalid API key. Rotate the key at Settings > API Keys.402 Payment Required
Insufficient credits. Top up at Settings > Cost. Do not retry until credits are available.403 Forbidden
The key is valid but the request is not allowed. Usually one of:- Pipeline-scope mismatch: key is tied to a different pipeline than the URL. Switch to a workspace-scoped key or regenerate a key for the right pipeline.
- Plan-level limit exceeded (optimization sessions, playground requests).
- Feature requires a paid plan (e.g. Active mode requires Core).
404 Not Found
The pipeline or model id in the request does not exist. Check at Deployments.409 Conflict
Idempotency conflict. Reuse anIdempotency-Key only for the same method, route, and request body.
422 Unprocessable Entity
The request was syntactically valid but cannot be processed safely. For replay-safe chat and Responses requests, this can mean the original idempotent response was too large to replay. Use a newIdempotency-Key only when you intentionally want a new inference request.
429 Too Many Requests
Per-key rate limit exceeded. Respect theRetry-After header. See Rate limits.
500 Internal Server Error
Unexpected server-side error. Retry once with backoff. If it persists, capture theX-Request-Id header and include it in your support ticket.
502 Bad Gateway
The upstream serving backend returned a transient failure. Retry once, then inspect deployment health.503 Service Unavailable
The target deployment is stopped, provisioning, or at capacity. Respect theRetry-After header.
504 Gateway Timeout
The request took longer than the allowed window. For large generations, switch to streaming (Streaming cookbook) or lowermax_tokens.
Retryable vs non-retryable
| Status | Retry? | Strategy |
|---|---|---|
| 400, 401, 403, 404 | No | Fix the request, key, or pipeline |
| 402 | No | Add credits or change billing state |
| 409 | No | Use a new idempotency key, or resend the exact same request body |
| 422 | No | Use a new idempotency key only when you want a new inference request |
| 429 | Yes | Respect Retry-After, exponential backoff |
| 500 | Once | Alert if it persists |
| 502 | Once | Retry once, then inspect deployment health |
| 503 | Yes | Respect Retry-After |
| 504 | Yes | Lower max_tokens or switch to streaming |
Request IDs
Every response carriesX-Request-Id. Include it in support tickets so the team can correlate logs to your request.
Next steps
Rate limits
How 429 works, how to raise your budget.
Authentication
Key scopes and rotation.
Troubleshooting
Recovery flows by error category.
Monitoring
Error rate tracking.