Error format
json
{
"error": {
"code": "model_not_allowed",
"message": "This key is not permitted to use this model."
}
}Error messages are sanitized and do not forward the provider’s raw error body. Use the stable error.code for handling logic. Not every denial has a generation ID, but every HTTP response has X-Request-ID.
Error reference
| HTTP | Code | Action |
|---|---|---|
| 400 | unsupported_parameter | Remove unsupported fields such as tools, provider routing, or response_format. |
| 400 | invalid_messages | Supply 1–64 valid text messages with supported roles. |
| 400 | invalid_max_tokens / invalid_temperature | Use values within the documented and model-specific bounds. |
| 400 | input_too_large | Shorten the messages; the gateway uses a conservative byte-based bound. |
| 400 | invalid_idempotency_key | Use 1–100 ASCII letters, digits, hyphens, or underscores. |
| 401 | invalid_api_key | Check the environment, full key value, and key status. |
| 402 | insufficient_credits / key_budget_exceeded | Check available balance, pending holds, and key limit; reduce max_tokens if appropriate. |
| 402 | staging_spend_limit | The aggregate internal test budget is exhausted or reserved. |
| 403 | model_not_approved / model_not_allowed / model_unavailable | Choose a configured, accessible model; unavailable aliases cannot be bypassed. |
| 403 | healthcare_policy_denied | Inspect workspace healthcare controls and the safe error message. |
| 403 | onboarding_required | Complete the current live account onboarding before usage. |
| 409 | request_already_submitted / idempotency_conflict | Reconcile the original request. Do not assume a duplicate returns the original text. |
| 413 | body_too_large | Keep the JSON body within 4 MiB for completions (256 KiB for dashboard APIs). |
| 415 | content_type | Send Content-Type: application/json. |
| 422 | sensitive_output_pattern | Synthetic-mode output was withheld after an identifier pattern; completed usage remains charged. |
| 429 | rate_limit | Pause dispatch and retry later with bounded backoff and the same logical request ID. |
| 502 | provider_rejected | Known upstream rejection; the reserved credits were released. |
| 502 | provider_outcome_unknown / invalid_provider_usage | Outcome or accounting needs review. Credits remain reserved; avoid an automatic new request. |
| 500 | internal_error | Keep the X-Request-ID and inspect activity before resubmitting. |
Safe troubleshooting
- Record the HTTP status, error code, request IDs, model alias, and timestamp.
- Check the key’s model permissions, balance, held credits, and Activity entry.
- For healthcare denials, review the account and route status; do not downgrade the data label or change providers to evade a failed policy.
- For uncertain outcomes, keep the original idempotency key and follow reconciliation guidance.
Never send raw keys, prompts, patient details, or responses in a troubleshooting report. There is no published support SLA or public incident-status endpoint yet.