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`
`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.

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

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: 60 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`)

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)

​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`)

Model not found (`404`)

Rate limit exceeded (`429`)

Internal server error (`500`)

Getting help