Errors | Omni Docs

Every Developer Preview route returns the same safe envelope:

{
  "error": {
    "code": "rate_limited",
    "message": "Request limit reached",
    "retryable": true,
    "retry_after_seconds": 5,
    "request_id": "request_...",
    "docs_url": "https://omni.channel/docs/api/errors#rate_limited",
    "details": {}
  }
}

Keep request_id when reporting a problem. Raw upstream exceptions are not part of the public contract.

Code	Retry?	Caller action
`validation_error`	No	Fix fields, types, identifiers, or unknown fields.
`unauthorized`	No	Supply a valid, non-revoked PAT.
`insufficient_scope`	No	Create or use a key with the required scope.
`not_found`	No	Verify the public ID and workspace. The API does not reveal inaccessible resources.
`idempotency_conflict`	No	Use the original body or a new key for new work.
`vault_not_ready`	No	Poll Vault state until `ready`, then make a new request.
`file_too_large`	No	Reduce the upload to a supported size.
`upload_missing`	No	PUT ciphertext before completing.
`upload_size_mismatch`	No	Re-encrypt/reserve using the exact expected size.
`quota_exceeded`	No	Delete unneeded files or wait for quota policy to change.
`rate_limited`	Yes	Honor `retry_after_seconds`, then retry with jitter.
`service_unavailable`	Yes	Retry with bounded exponential backoff and the same idempotency key.