Error Codes

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

{
  "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).

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`
`400`	Undecodable video on the video path	`invalid_request_error`	n/a
`403`	Invalid API key	Plain `"Invalid API Key"` detail	n/a
`404`	Unknown model	`model_not_found`	n/a
`422`	Request validation failure	FastAPI validation error	n/a
`429`	Rate limit exceeded	`rate_limit_exceeded`	n/a
`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.

{
  "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 or the 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.

Invalid video (`400`)

Returned when a video_url on the chat-completions video path points to a file that cannot be decoded (unsupported container, corrupt stream, or a URL that does not resolve to a video). The Gateway returns a 400 with error.type = "invalid_request_error" rather than a 500.

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.

Rate limit exceeded (`429`)

Returned when a per-tier request quota is exhausted. See Rate Limits for bucket sizes and tier attribution.

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 120 per 1 minute",
    "tier": "anonymous"
  }
}

Anonymous callers receive a message pointing to 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.

{
  "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 and the Chat Completions API reference for retry-relevant request parameters.

Overview

Guides

API Reference

Misc

HTTP status codes

Common errors

Capability violation (`400`)

Invalid document (`400`)

Invalid video (`400`)

Model not found (`404`)

Rate limit exceeded (`429`)

Internal server error (`500`)

Getting help

​HTTP status codes

​Common errors

​Capability violation (400)

​Invalid document (400)

​Invalid video (400)

​Model not found (404)

​Rate limit exceeded (429)

​Internal server error (500)

​Getting help

HTTP status codes

Common errors

Capability violation (`400`)

Invalid document (`400`)

Invalid video (`400`)

Model not found (`404`)

Rate limit exceeded (`429`)

Internal server error (`500`)

Getting help