Skip to main content
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

StatusWhenerror.typeerror.code
400Capability mismatch (wrong media type for model)invalid_request_errorcapability_violation
400Invalid or unreadable PDFinvalid_request_errorinvalid_document
403Invalid API key— (plain "Invalid API Key" detail)—
404Unknown modelmodel_not_found—
422Request validation failureFastAPI validation error—
429Rate limit exceededrate_limit_exceeded—
500Uncaught server errorinternal_server_errorinternal_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.