Skip to content

Errors

The error body, which failures to retry, and every error code.

The error body

A failure is a 4xx or 5xx whose body has success: false:

FieldTypeWhat it is
error.codestringOne of the codes below. Branch on this, not on the message.
error.messagestringThe code's meaning in a sentence.
error.retryablebooleanWhether the same request can succeed later.
error.fieldsobject or nullFor VALIDATION_FAILED, what is wrong with each field, by its path.
requestIdstringThis call's id.
latencyMsnumberHow long the call took, in milliseconds.

Retrying

Retry only when error.retryable is true, after a backoff, and after the Retry-After header’s seconds where one is sent. Retrying a request that is not retryable cannot succeed: fix the request, or for QUOTA_EXCEEDED and INSUFFICIENT_BALANCE, the account. When the outcome is uncertain (OUTCOME_UNCERTAIN), retry with the same Idempotency-Key.

Every error code

Each API’s page lists the codes it can return. This is the full list, from the platform’s error registry.

CodeStatusMeaningRetrying
API_VERSION_UNSUPPORTED400That API version is no longer supported.Do not retry automatically
IDEMPOTENCY_KEY_INVALID400That Idempotency-Key does not meet the required format.Do not retry automatically
IDEMPOTENCY_KEY_REQUIRED400An Idempotency-Key header is required for this request.Do not retry automatically
REQUEST_MALFORMED400The request could not be parsed.Do not retry automatically
AUTH_KEY_EXPIRED401The API key is not valid.Do not retry automatically
AUTH_KEY_INVALID401The API key is not valid.Do not retry automatically
AUTH_KEY_MISSING401No API key was presented.Do not retry automatically
AUTH_KEY_REVOKED401The API key is not valid.Do not retry automatically
FLOW_GRANT_INVALID401That flow grant is not valid.Do not retry automatically
PLAYGROUND_GRANT_INVALID401That playground grant is not valid.Do not retry automatically
INSUFFICIENT_BALANCE402The available balance is not enough for this request.Do not retry automatically
AUTH_IP_NOT_ALLOWED403This API key may not be used from this address.Do not retry automatically
ENTITLEMENT_MISSING403This organization is not entitled to that product in this environment.Do not retry automatically
ORGANIZATION_SUSPENDED403This organization is not active.Do not retry automatically
PRODUCT_NOT_AVAILABLE403That product is not available.Do not retry automatically
PRODUCT_RETIRED403That product has been withdrawn.Do not retry automatically
SCOPE_INSUFFICIENT403This API key does not carry the scope this product requires.Do not retry automatically
DIGILOCKER_SESSION_NOT_FOUND404No open DigiLocker session has that id.Do not retry automatically
FLOW_NOT_FOUND404No such flow.Do not retry automatically
FLOW_RUN_NOT_FOUND404No such flow run.Do not retry automatically
FLOW_VERSION_NOT_FOUND404That version of the flow does not exist.Do not retry automatically
NOT_FOUND404The requested resource was not found.Do not retry automatically
OCR_JOB_NOT_FOUND404No such job.Do not retry automatically
PRODUCT_NOT_FOUND404No such product.Do not retry automatically
DIGILOCKER_CONSENT_PENDING409The person has not yet given consent on DigiLocker.Safe to retry
DIGILOCKER_STEP_INVALID409The DigiLocker session is not at this step.Do not retry automatically
FLOW_LIMIT_REACHED409This organization has reached its limit of flows.Do not retry automatically
FLOW_NODE_NOT_AWAITING409That step is not waiting for a code.Do not retry automatically
FLOW_REVISION_CONFLICT409The flow was changed by someone else. Reload and edit again.Do not retry automatically
FLOW_RUN_NOT_CANCELLABLE409That flow run has already finished.Do not retry automatically
IDEMPOTENCY_KEY_REUSED409That idempotency key was already used for a different request.Do not retry automatically
PRICE_UNAVAILABLE409No active price covers this product right now.Safe to retry
REQUEST_IN_PROGRESS409An earlier attempt with this key is still running.Safe to retry
SETTLEMENT_PENDING409This request is awaiting reconciliation by an operator.Do not retry automatically
API_VERSION_SUNSET410That API version passed its announced sunset date.Do not retry automatically
OCR_RESULT_EXPIRED410That result is no longer retained.Do not retry automatically
OCR_FILE_TOO_LARGE413The document is too large.Do not retry automatically
REQUEST_TOO_LARGE413The request body is too large.Do not retry automatically
OCR_UNSUPPORTED_MEDIA_TYPE415That document format is not accepted.Do not retry automatically
UNSUPPORTED_MEDIA_TYPE415That content type is not accepted on this route.Do not retry automatically
CONSENT_REQUIRED422This product requires an explicit consent flag.Do not retry automatically
DIGILOCKER_CONSENT_DENIED422The person did not give consent on DigiLocker.Do not retry automatically
DIGILOCKER_DETAILS_MISMATCH422The details do not match the person's DigiLocker record.Do not retry automatically
DIGILOCKER_OTP_INVALID422The code was not accepted. Ask the person for the code they received and try again.Do not retry automatically
DIGILOCKER_SESSION_EXPIRED422The DigiLocker session has expired. Start a new session.Do not retry automatically
FLOW_INVALID422The flow cannot be saved or run as it stands. See the listed problems.Do not retry automatically
OCR_DOCUMENT_TYPE_MISMATCH422The document is not the type this product reads.Do not retry automatically
OCR_INPUT_CORRUPT422The document could not be decoded.Do not retry automatically
OCR_LOW_CONFIDENCE422The document could not be read with enough confidence. Retry with a clearer image.Safe to retry
OCR_PAGE_LIMIT_EXCEEDED422The document has more pages than this product accepts.Do not retry automatically
OCR_UNREADABLE422No text could be found in the document. Retry with a clearer image.Safe to retry
SANDBOX_FIXTURE_MISSING422No sandbox fixture exists for this input. Use a different test value.Do not retry automatically
UPSTREAM_REJECTED422The upstream source rejected the input.Do not retry automatically
VALIDATION_FAILED422The request payload is invalid.Do not retry automatically
CONCURRENCY_LIMIT429Too many simultaneous requests.Safe to retry
FLOW_GRANT_EXHAUSTED429That flow grant has no uses left.Do not retry automatically
FLOW_RUN_LIMIT_REACHED429Too many flow runs are active.Safe to retry
OCR_QUEUE_SATURATED429The document queue is full. Retry shortly.Safe to retry
PLAYGROUND_GRANT_EXHAUSTED429That playground grant has no uses left.Do not retry automatically
QUOTA_EXCEEDED429The allowance for this window is spent.Do not retry automatically
RATE_LIMITED429Too many requests.Safe to retry
INTERNAL_ERROR500An unexpected error occurred.Safe to retry
OUTCOME_UNCERTAIN502The outcome of this request is not yet known. Retry with the same Idempotency-Key.Do not retry automatically
UPSTREAM_UNAVAILABLE502The upstream source is unavailable. Retry shortly.Safe to retry
MAINTENANCE_MODE503The service is in a maintenance window.Safe to retry
NO_PROVIDER_AVAILABLE503No provider can serve this product right now.Safe to retry
OCR_UNAVAILABLE503Document reading is unavailable right now. Retry later.Safe to retry
SERVICE_OVERLOADED503The service is shedding load. Retry shortly.Safe to retry
OCR_TIMEOUT504The document took too long to process. Retry shortly.Safe to retry
UPSTREAM_TIMEOUT504The upstream source did not respond in time.Safe to retry

Written from FinSour platform API contract (finsour development at 80e8b83bf), last changed . OpenAPI document at commit 436311c32, API version 2026-11-01. The beta is served from the staging gateway.