> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nomask.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope and every error code the API returns.

Errors use the OpenAI envelope, so SDK exception types work as expected. Every response, success or failure, carries an `X-Request-Id` header; include it when contacting support.

## The error envelope

```json theme={"system"}
{
  "error": {
    "message": "You are sending requests too quickly. Slow down and retry after 21 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "param": null
  }
}
```

`type` follows the OpenAI convention (`invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error`, `server_error`). `code` is the precise machine-readable reason, and `param` names the offending request field when there is one.

## Status codes

| Status | Type | When |
| - | - | - |
| 400 | `invalid_request_error` | Malformed body, invalid or unsupported parameter, bad image, context too long, or a content policy violation. |
| 401 | `authentication_error` | Missing, incorrect, revoked, or expired API key. |
| 402 | `invalid_request_error` | Your API balance is empty. |
| 403 | `permission_error` | Your account does not have API access. |
| 404 | `invalid_request_error` | Unknown model or unknown endpoint. |
| 413 | `invalid_request_error` | Request payload too large. |
| 429 | `rate_limit_error` | Rate limit or a key's monthly spending limit reached. |
| 500 | `server_error` | Internal error. Safe to retry. |
| 502 | `server_error` | The model failed to produce a response. Safe to retry. |
| 503 | `server_error` | Model busy or overloaded, or the API is in maintenance. Retry with backoff. |
| 504 | `server_error` | The model timed out. Safe to retry. |

## Error code reference

| Code | Status | Meaning |
| - | - | - |
| `missing_parameter` | 400 | A required field (like `model` or `messages`) is absent. |
| `invalid_parameter` | 400 | A field has the wrong type or is out of range. `param` names it. |
| `unsupported_parameter` | 400 | A recognized OpenAI field this API does not support (e.g. `logprobs`). |
| `invalid_request` | 400 | The body is not a JSON object, or another structural problem. |
| `model_lacks_vision` | 400 | An image was sent to a non-vision model. |
| `model_lacks_video` | 400 | The selected model does not accept video. Choose a model marked Video input. |
| `invalid_video` / `video_unsupported_format` / `video_duration_exceeded` / `video_fetch_failed` | 400 | The clip could not be read or exceeds this model's format or duration limits. See [Video Inputs](https://docs.nomask.ai/video-inputs.md). |
| `video_too_large` | 413 | The actual video file exceeds this model's maximum file size. |
| `model_lacks_function_calling` | 400 | `tools` was sent to a model without the function\_calling capability. |
| `invalid_image` | 400 | Corrupted, too small, too large, or unsupported image. |
| `context_length_exceeded` | 400 | The conversation does not fit the model's context window. Shorten it or pick a larger-context model. |
| `content_policy_violation` | 400 | The request was flagged by the content policy, or the model's response was blocked by a content filter. Rephrase the prompt and retry; some models apply stricter filtering than others. |
| `missing_api_key` / `invalid_api_key` / `api_key_expired` / `api_key_revoked` | 401 | Authentication problems; see [Authentication](https://docs.nomask.ai/authentication.md). |
| `insufficient_balance` | 402 | Your balance is empty. Fund it from the dashboard. |
| `account_restricted` | 403 | The account is not allowed to use the API. |
| `model_not_found` | 404 | Unknown or disabled model id. |
| `unknown_endpoint` | 404 | The path does not exist under /v1. |
| `payload_too_large` | 413 | The request body exceeds the size limit. |
| `rate_limit_exceeded` | 429 | A request allowance or the text token allowance was reached. Honor `Retry-After`. |
| `monthly_limit_exceeded` | 429 | The key hit its monthly USD cap. |
| `internal_error` | 500 | Unexpected server error. |
| `upstream_error` / `upstream_unavailable` / `invalid_upstream_response` | 502 | The model failed to generate. Retry. |
| `model_overloaded` | 503 | The model is at capacity right now. |
| `model_busy` | 503 | The model is temporarily busy. Retry later or switch models; this is not your account limit. |
| `service_unavailable` | 503 | The API is temporarily disabled for maintenance. |
| `video_input_unavailable` | 503 | Video processing is temporarily unavailable. Retry later. |
| `timeout` | 504 | The model took too long to respond. |

## Handling errors

* Retry `5xx` and `429` with exponential backoff; honor `Retry-After` when present.
* Do not retry `400`/`401`/`402`/`403`/`404` unchanged; fix the request or account state first.
* Use [idempotency keys](https://docs.nomask.ai/idempotency.md) so network-level retries can never double-bill.
* Log the `X-Request-Id` header with failures; it lets support trace the exact request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.