> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Omni API errors and retries

> Understand the error responses the Omni API returns, including during scheduled maintenance, and which ones are safe to retry.

The Omni API returns standard HTTP status codes. Error responses have a JSON body with a `message` field that describes the problem.

```json theme={null}
{
  "error": "<response_code>",
  "message": "<error_reason>"
}
```

## Status codes

| Status                      | Meaning                                                                                            | Retry?                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `4xx`                       | The request is invalid, unauthenticated, unauthorized, or refers to something that does not exist. | No. Fix the request first.                                                         |
| `429 Too Many Requests`     | You exceeded the [rate limit](/api/rate-limits).                                                   | Yes, with exponential backoff.                                                     |
| `500 Internal Server Error` | Omni hit an unexpected error while handling the request.                                           | Once, with backoff. If it persists, contact Omni Support with the request details. |
| `503 Service Unavailable`   | Omni is undergoing [scheduled maintenance](#scheduled-maintenance).                                | Yes, after the interval in the `Retry-After` header.                               |

## Scheduled maintenance

During scheduled maintenance, every machine-called endpoint returns `503 Service Unavailable` with a `Retry-After` header. The header value is the number of seconds to wait before you retry. The body matches what the endpoint's clients already parse.

<Tabs>
  <Tab title="REST APIs" icon="cloud" id="rest-api">
    REST APIs - including `/api/...`, [embed SSO URL generation](/embed/setup/standard-sso/latest), git webhooks return:

    ```http wrap theme={null}
    HTTP/2 503
    Content-Type: application/json
    Retry-After: 300
    Cache-Control: no-store

    {
      "detail": "Omni is undergoing scheduled maintenance. Retry after the Retry-After interval.",
      "message": "Service Unavailable",
      "status": 503
    }
    ```
  </Tab>

  <Tab title="SCIM APIs" icon="users" id="scim-api">
    SCIM APIs (`/api/scim/...`) return a [SCIM error envelope](https://datatracker.ietf.org/doc/html/rfc7644#section-3.12):

    ```http wrap theme={null}
    HTTP/2 503
    Content-Type: application/scim+json
    Retry-After: 300

    {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
      "status": 503,
      "detail": "Omni is undergoing scheduled maintenance. Retry after the Retry-After interval."
    }
    ```
  </Tab>

  <Tab title="MCP" icon="database" id="scim-api">
    The MCP server (`/mcp` and the connector endpoint) return a JSON-RPC 2.0 error envelope:

    ```http wrap theme={null}
    HTTP/2 503
    Content-Type: application/json
    Retry-After: 300

    {
      "jsonrpc": "2.0",
      "id": null,
      "error": {
        "code": -32000,
        "message": "Service Unavailable",
        "data": "Omni is undergoing scheduled maintenance. Retry after the Retry-After interval."
      }
    }
    ```
  </Tab>

  <Tab title="OAuth token & registration" icon="key" id="scim-api">
    OAuth token and client registration (`/oauth/token`, `/oauth/register`) return an [RFC 6749 error object](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2):

    ```http theme={null}
    HTTP/2 503
    Content-Type: application/json
    Retry-After: 300

    {
      "error": "temporarily_unavailable",
      "error_description": "Omni is undergoing scheduled maintenance. Retry after the Retry-After interval."
    }
    ```
  </Tab>

  <Tab title="OAuth discovery documents" icon="file" id="oauth-documents">
    OAuth discovery documents (`/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/.well-known/openid-configuration`) return `503` with `Retry-After` and no body, so discovery clients do not misread an error page as a misconfigured server.
  </Tab>
</Tabs>

Paths are matched without regard to case. Browser pages, including the OAuth consent screens, show a maintenance page with a `200` instead.

Maintenance windows are short. A client that waits for the `Retry-After` interval and retries resumes on its own with no other change.

<Note>
  Requests that a maintenance `503` rejects were not processed. It is safe to send them again.
</Note>

## Retry guidance

* Retry `429` and `503` responses. Do not retry other `4xx` responses.
* When a response includes `Retry-After`, wait at least that many seconds. Otherwise, use exponential backoff with jitter, for example 1, 2, 4, and 8 seconds.
* Cap the number of attempts. A `500` that repeats is a problem to report, not one to retry through.
* Do not retry in a tight loop. Rapid retries during an incident make recovery slower.

## Next steps

* [Rate limits](/api/rate-limits)
* [Authentication](/api/authentication)
* [Base URL](/api/base-url)