service_unavailable (503)

← Error reference

service_unavailable

HTTP status: 503

Retryable: Yes. The request did not change server state.

The ID scan service is temporarily unavailable.

When it fires

The ID scan API could not complete the request because the scan service was not ready or timed out. We fail closed rather than return a partial result. The document was not charged.

How to handle it

Retry with exponential backoff: this is usually transient. If you sent an `Idempotency-Key`, send a new one on the retry: for 24 hours, a byte-identical retry with the same key replays this 503, and a rebuilt multipart body gets `409 idempotency_conflict`. Persistent occurrences are an internal incident; contact support with the `request_id` from the response rather than retrying indefinitely.

Example response

{
  "error": {
    "type": "https://docs.checktiv.com/api/errors/service_unavailable",
    "code": "service_unavailable",
    "message": "The ID scan service is temporarily unavailable. Retry shortly.",
    "request_id": "req_01HEXAMPLE0000000000000000",
    "doc_url": "https://docs.checktiv.com/api/errors/service_unavailable"
  }
}