> ## Documentation Index
> Fetch the complete documentation index at: https://oma-codex-339-workspace-permissions.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand OMA status codes, error envelopes, and request IDs.

OMA public APIs use a consistent compatibility error envelope.

```json theme={null}
{
  "type": "error",
  "request_id": "req_01...",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}
```

<ResponseField name="type" type="string">
  The top-level object type. Error responses use `error`.
</ResponseField>

<ResponseField name="request_id" type="string">
  The trace ID for this request. Include it when contacting the deployment operator.
</ResponseField>

<ResponseField name="error.type" type="string">
  A stable category such as `authentication_error`, `invalid_request_error`, or `not_found_error`.
</ResponseField>

<ResponseField name="error.message" type="string">
  A developer-facing explanation. Do not branch on the complete message text.
</ResponseField>

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

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