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 image or video	`invalid_request_error`	`invalid_media`
`402`	The organization’s credits are exhausted	Plain detail	n/a
`403`	Invalid API key	Plain `"Invalid API Key"` detail	n/a
`404`	Unknown model, or unknown completion id	`model_not_found`	n/a
`422`	Request validation failure	FastAPI validation error	n/a
`429`	Rate limit exceeded, or the request queue is full	`rate_limit_exceeded`	n/a
`500`	Uncaught server error	`internal_server_error`	`internal_error`
`503`	The model deployment is not serving	`service_unavailable`	`model_unavailable`
`504`	Model did not respond within the dispatch window	`gateway_timeout`	`inference_timeout`

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 media (`400`)

Returned when an image_url or a video_url points to a file the Gateway cannot decode: an unsupported container, a corrupt stream, a URL that does not resolve to media, or malformed base64. The Gateway returns a 400 with error.type = "invalid_request_error" and error.code = "invalid_media" rather than a 500. error.param names the offending content part.

Credits exhausted (`402`)

Returned when an authenticated caller’s organization has no credit left.

{
  "detail": "Access denied. Your credits are exhausted. Please move to Pay-As-You-Go to continue using the service."
}

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. Every public OpenAI route shares one budget per caller. See Rate Limits for bucket sizes and tier attribution.

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Get a free API key at https://app.vlm.run/dashboard/settings/api-keys for higher limits.",
    "tier": "anonymous"
  }
}

Anonymous callers receive the message above and an X-VLMRun-Upgrade header. Authenticated callers receive Rate limit exceeded: <window>. Every 429 carries Retry-After, holding the longest exhausted window, so one wait of that length is enough. Retry after it elapses. A full request queue answers 429 too, with Retry-After: 60. The queue holds 128 waiting requests. That is capacity rather than quota, so the same call succeeds on retry.

Model unavailable (`503`)

Returned when the model’s deployment is not serving traffic, for example during a cold start. Retry-After carries the suggested wait, 30 seconds by default. This is distinct from the 504, which means the model accepted the request and then ran past the dispatch window.

{
  "detail": {
    "error": {
      "message": "Model 'zai-org/glm-ocr' is temporarily unavailable. Please retry shortly.",
      "type": "service_unavailable",
      "code": "model_unavailable"
    }
  }
}

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.

Inference timeout (`504`)

Returned when the model does not return a response inside the Gateway’s dispatch window. The Gateway aborts the request after 270 seconds by default. That window is configurable per deployment, is subject to change, and is not a documented SLA.

{
  "detail": {
    "error": {
      "message": "Model <model-id> did not respond within 270s and was aborted. Please retry shortly.",
      "type": "gateway_timeout",
      "code": "inference_timeout",
      "param": null
    }
  }
}

The non-streaming path returns no partial result when the Gateway aborts the request. A timeout can happen when a model deployment is not yet serving traffic or is under heavy load. To reduce the chance of a timeout:

Retry after a short delay with exponential backoff.
Keep your client-side timeout above the Gateway’s dispatch window. An OpenAI SDK client with a low timeout= value can fail earlier with its own error.
Chunk the workload so each request carries a smaller payload.
Use stream=true so tokens arrive as the model produces them.

Capture the x-request-id response header and include it when contacting support@vlm.run.

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 media (`400`)

Credits exhausted (`402`)

Model not found (`404`)

Rate limit exceeded (`429`)

Model unavailable (`503`)

Internal server error (`500`)

Inference timeout (`504`)

Getting help

​HTTP status codes

​Common errors

​Capability violation (400)

​Invalid document (400)

​Invalid media (400)

​Credits exhausted (402)

​Model not found (404)

​Rate limit exceeded (429)

​Model unavailable (503)

​Internal server error (500)

​Inference timeout (504)

​Getting help

HTTP status codes

Common errors

Capability violation (`400`)

Invalid document (`400`)

Invalid media (`400`)

Credits exhausted (`402`)

Model not found (`404`)

Rate limit exceeded (`429`)

Model unavailable (`503`)

Internal server error (`500`)

Inference timeout (`504`)

Getting help