Errors

OMA public APIs use a consistent compatibility error envelope.

{
  "type": "error",
  "request_id": "req_01...",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}

string

The top-level object type. Error responses use error.

string

The trace ID for this request. Include it when contacting the deployment operator.

string

A stable category such as authentication_error, invalid_request_error, or not_found_error.

string

A developer-facing explanation. Do not branch on the complete message text.

Common status codes

Status	Meaning	Action
`400`	Invalid fields, pagination, or beta parameters	Correct the request before retrying
`401`	Missing or unrecognized credentials	Check the API key and authentication header
`403`	The identity lacks a required permission	Check the workspace and resource permissions
`404`	The route or tenant-scoped resource does not exist	Check the path and resource ID
`409`	A resource version or state conflict	Retrieve the resource again before updating
`413`	The request body or uploaded file is too large	Reduce the request or review deployment limits
`429`	Upstream or deployment rate limiting	Honor `Retry-After` or use exponential backoff
`500`	Internal service error	Use `request_id` to inspect service logs
`502`	Upstream model or proxy connection failed	Check upstream health and retry with a bound
`503`	Required upstream configuration or dependency is unavailable	Fix deployment configuration before retrying

Retries

Use jittered exponential backoff only for temporary network failures, 429, or explicitly recoverable 5xx responses. Validation, authentication, and version conflicts require a request change and will not succeed through blind retries.

/v1/filestore uses a flat error format required by the rclone-filestore protocol instead of the general envelope on this page.

Get started

Core API

Managed Agents

Webhooks

Common status codes

Retries

​Common status codes

​Retries

Common status codes

Retries