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

# Errors

> Error codes and handling.

The API uses standard HTTP status codes and a consistent error object, so you can route failures quickly and recover with less guesswork.

## Error response format

```json theme={null}
{
  "error": {
    "message": "Unsupported resolution '4K' for model 'seedream-5-lite'.",
    "type": "invalid_request_error",
    "param": "resolution",
    "code": "invalid_parameter"
  }
}
```

| Field     | Type           | Description                                                |
| --------- | -------------- | ---------------------------------------------------------- |
| `message` | string         | Human-readable description of the error                    |
| `type`    | string         | Always `invalid_request_error`                             |
| `param`   | string or null | The request parameter that caused the error, if applicable |
| `code`    | string         | Machine-readable error code                                |
| `doc_url` | string         | Link to relevant documentation, when available             |

## Error codes

| Code                       | HTTP status | Description                                               | Retryable |
| -------------------------- | ----------- | --------------------------------------------------------- | --------- |
| `invalid_api_key`          | 401         | Missing, malformed, revoked, or invalid API key           | No        |
| `parameter_missing`        | 400         | A required parameter was not provided                     | No        |
| `invalid_parameter`        | 400         | A parameter value is not supported for the selected model | No        |
| `quota_exceeded`           | 402         | Insufficient account balance or quota                     | No        |
| `content_policy_violation` | 422         | Prompt or reference image input failed safety checks      | No        |
| `rate_limit`               | 429         | Too many requests                                         | Yes       |
| `not_found`                | 404         | The requested resource does not exist                     | No        |
| `server_error`             | 500         | Unexpected server-side error                              | Yes       |

## Handling errors

Use the HTTP status code and `error.code` together. The status code tells you whether the failure is temporary. The error code tells you what to fix next.

### Retryable failures

Retry `429` and `500` responses with exponential backoff.

* For `429`, wait for the `Retry-After` header.
* For `500`, use backoff with a timeout or retry limit.
* Log the generation ID when you have one so you can trace the failed generation.

See [Rate limits](/guides/rate-limits) for details.

### Terminal failures

Do not retry `400`, `401`, `402`, `404`, or `422` until you change the request or account state.

* `400`: fix missing or invalid parameters
* `401`: fix your API key
* `402`: add credits or resolve quota limits
* `404`: verify the resource ID or path
* `422`: revise the prompt or reference image input

## Async video failures

Video generations can fail after submission. When you poll `GET /v2/videos/generations/{id}`, the response can return `status: "failed"` with an error object.

```json theme={null}
{
  "id": "req-01HXYZVIDEO1234",
  "status": "failed",
  "error": {
    "message": "Upstream provider request timed out.",
    "code": "server_error"
  }
}
```

Treat `failed` as a terminal state for that generation. Read `error.message`, fix the input or retry policy, and submit a new generation when you're ready.

See [Generate videos](/guides/generate-videos) for a polling example.