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

# Error Codes

> HTTP errors returned by the VLM Run Gateway API

The VLM Run Gateway returns OpenAI-compatible error bodies for most failure modes.
Errors are wrapped in a `detail` object when returned by FastAPI:

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "detail": {
    "error": {
      "message": "Human-readable description",
      "type": "invalid_request_error",
      "code": "capability_violation",
      "param": "messages"
    }
  }
}
```

Rate limit errors use a top-level `error` object instead (see
[Rate Limits](/gateway/rate-limits)).

## HTTP status codes

| Status | When                                             | `error.type`                         | `error.code`           |
| ------ | ------------------------------------------------ | ------------------------------------ | ---------------------- |
| `400`  | Capability mismatch (wrong media type for model) | `invalid_request_error`              | `capability_violation` |
| `400`  | Invalid or unreadable PDF                        | `invalid_request_error`              | `invalid_document`     |
| `403`  | Invalid API key                                  | — (plain `"Invalid API Key"` detail) | —                      |
| `404`  | Unknown model                                    | `model_not_found`                    | —                      |
| `422`  | Request validation failure                       | FastAPI validation error             | —                      |
| `429`  | Rate limit exceeded                              | `rate_limit_exceeded`                | —                      |
| `500`  | Uncaught server error                            | `internal_server_error`              | `internal_error`       |

## Common errors

### Capability violation (`400`)

Returned when the request content does not match the model's declared
capabilities. For example, sending a `document_url` to a model that only
accepts images, or sending multiple images to a single-image OCR model.

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "detail": {
    "error": {
      "message": "Model 'paddleocr/pp-ocrv6' does not accept document_url together with image_url parts.",
      "type": "invalid_request_error",
      "code": "capability_violation",
      "param": "messages.content.document_url"
    }
  }
}
```

Check each model's capabilities on
[`GET /v1/openai/models`](/gateway/api-reference/get-models) or the
[Models](/gateway/models) page before sending a request.

### Invalid document (`400`)

Returned when a `document_url` points to a file that is not a
valid PDF, exceeds size limits, or cannot be decoded.

### Model not found (`404`)

Returned when the `model` field does not match any registered model or alias.
List available models with [`GET /v1/openai/models`](/gateway/api-reference/get-models).

### Rate limit exceeded (`429`)

Returned when a per-tier request quota is exhausted. See
[Rate Limits](/gateway/rate-limits) for bucket sizes and tier attribution.

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 60 per 1 minute",
    "tier": "anonymous"
  }
}
```

Anonymous callers receive a message pointing to
[app.vlm.run](https://app.vlm.run) to sign up for an API key. Authenticated
callers receive a generic rate limit message.

### Internal server error (`500`)

Uncaught exceptions return a sanitized body with no stack traces or internal
paths. Every response includes an `x-request-id` header. On sanitized `500`
errors, the same id is also returned as `error.request_id` in the JSON body.
Include either value when contacting [support@vlm.run](mailto:support@vlm.run).

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "error": {
    "message": "Internal server error. Please retry; if the problem persists, contact support with the request id.",
    "type": "internal_server_error",
    "code": "internal_error",
    "request_id": "550e8400e29b41d4a716446655440000"
  }
}
```

You may send an `x-request-id` request header to supply your own correlation
id; the Gateway echoes it on the response. When the header is omitted, the
Gateway mints a new id.

## Getting help

When reporting an issue, include:

* The `x-request-id` response header (or `error.request_id` on sanitized `500`
  responses)
* The HTTP status code and response body
* The `model` value and content part types you sent

See also [Rate Limits](/gateway/rate-limits) and the
[Chat Completions API reference](/gateway/api-reference/post-chat-completions)
for retry-relevant request parameters.