Omni API errors and retries

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

{
  "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.	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.	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.

REST APIs
SCIM APIs
MCP
OAuth token & registration
OAuth discovery documents

REST APIs - including /api/..., embed SSO URL generation, git webhooks return:

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
}

SCIM APIs (/api/scim/...) return a SCIM error envelope:

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."
}

The MCP server (/mcp and the connector endpoint) return a JSON-RPC 2.0 error envelope:

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."
  }
}

OAuth token and client registration (/oauth/token, /oauth/register) return an RFC 6749 error object:

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."
}

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.

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.

Requests that a maintenance 503 rejects were not processed. It is safe to send them again.

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.

Getting started

Who am I?

Administration APIs

AI APIs

App APIs

Connection APIs

Content APIs

Dashboard APIs

Document APIs

Embed APIs

Folder APIs

Label APIs

Model APIs

Query APIs

Schedule APIs

Upload APIs

User APIs

User group APIs

Omni API errors and retries

Status codes

Scheduled maintenance

Retry guidance

Next steps

​Status codes

​Scheduled maintenance

​Retry guidance

​Next steps

Status codes

Scheduled maintenance

Retry guidance

Next steps