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:
| Field | Type | What it is |
|---|---|---|
error.code | string | One of the codes below. Branch on this, not on the message. |
error.message | string | The code's meaning in a sentence. |
error.retryable | boolean | Whether the same request can succeed later. |
error.fields | object or null | For VALIDATION_FAILED, what is wrong with each field, by its path. |
requestId | string | This call's id. |
latencyMs | number | How 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.
| Code | Status | Meaning | Retrying |
|---|---|---|---|
API_VERSION_UNSUPPORTED | 400 | That API version is no longer supported. | Do not retry automatically |
IDEMPOTENCY_KEY_INVALID | 400 | That Idempotency-Key does not meet the required format. | Do not retry automatically |
IDEMPOTENCY_KEY_REQUIRED | 400 | An Idempotency-Key header is required for this request. | Do not retry automatically |
REQUEST_MALFORMED | 400 | The request could not be parsed. | Do not retry automatically |
AUTH_KEY_EXPIRED | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_INVALID | 401 | The API key is not valid. | Do not retry automatically |
AUTH_KEY_MISSING | 401 | No API key was presented. | Do not retry automatically |
AUTH_KEY_REVOKED | 401 | The API key is not valid. | Do not retry automatically |
FLOW_GRANT_INVALID | 401 | That flow grant is not valid. | Do not retry automatically |
PLAYGROUND_GRANT_INVALID | 401 | That playground grant is not valid. | Do not retry automatically |
INSUFFICIENT_BALANCE | 402 | The available balance is not enough for this request. | Do not retry automatically |
AUTH_IP_NOT_ALLOWED | 403 | This API key may not be used from this address. | Do not retry automatically |
ENTITLEMENT_MISSING | 403 | This organization is not entitled to that product in this environment. | Do not retry automatically |
ORGANIZATION_SUSPENDED | 403 | This organization is not active. | Do not retry automatically |
PRODUCT_NOT_AVAILABLE | 403 | That product is not available. | Do not retry automatically |
PRODUCT_RETIRED | 403 | That product has been withdrawn. | Do not retry automatically |
SCOPE_INSUFFICIENT | 403 | This API key does not carry the scope this product requires. | Do not retry automatically |
DIGILOCKER_SESSION_NOT_FOUND | 404 | No open DigiLocker session has that id. | Do not retry automatically |
FLOW_NOT_FOUND | 404 | No such flow. | Do not retry automatically |
FLOW_RUN_NOT_FOUND | 404 | No such flow run. | Do not retry automatically |
FLOW_VERSION_NOT_FOUND | 404 | That version of the flow does not exist. | Do not retry automatically |
NOT_FOUND | 404 | The requested resource was not found. | Do not retry automatically |
OCR_JOB_NOT_FOUND | 404 | No such job. | Do not retry automatically |
PRODUCT_NOT_FOUND | 404 | No such product. | Do not retry automatically |
DIGILOCKER_CONSENT_PENDING | 409 | The person has not yet given consent on DigiLocker. | Safe to retry |
DIGILOCKER_STEP_INVALID | 409 | The DigiLocker session is not at this step. | Do not retry automatically |
FLOW_LIMIT_REACHED | 409 | This organization has reached its limit of flows. | Do not retry automatically |
FLOW_NODE_NOT_AWAITING | 409 | That step is not waiting for a code. | Do not retry automatically |
FLOW_REVISION_CONFLICT | 409 | The flow was changed by someone else. Reload and edit again. | Do not retry automatically |
FLOW_RUN_NOT_CANCELLABLE | 409 | That flow run has already finished. | Do not retry automatically |
IDEMPOTENCY_KEY_REUSED | 409 | That idempotency key was already used for a different request. | Do not retry automatically |
PRICE_UNAVAILABLE | 409 | No active price covers this product right now. | Safe to retry |
REQUEST_IN_PROGRESS | 409 | An earlier attempt with this key is still running. | Safe to retry |
SETTLEMENT_PENDING | 409 | This request is awaiting reconciliation by an operator. | Do not retry automatically |
API_VERSION_SUNSET | 410 | That API version passed its announced sunset date. | Do not retry automatically |
OCR_RESULT_EXPIRED | 410 | That result is no longer retained. | Do not retry automatically |
OCR_FILE_TOO_LARGE | 413 | The document is too large. | Do not retry automatically |
REQUEST_TOO_LARGE | 413 | The request body is too large. | Do not retry automatically |
OCR_UNSUPPORTED_MEDIA_TYPE | 415 | That document format is not accepted. | Do not retry automatically |
UNSUPPORTED_MEDIA_TYPE | 415 | That content type is not accepted on this route. | Do not retry automatically |
CONSENT_REQUIRED | 422 | This product requires an explicit consent flag. | Do not retry automatically |
DIGILOCKER_CONSENT_DENIED | 422 | The person did not give consent on DigiLocker. | Do not retry automatically |
DIGILOCKER_DETAILS_MISMATCH | 422 | The details do not match the person's DigiLocker record. | Do not retry automatically |
DIGILOCKER_OTP_INVALID | 422 | The code was not accepted. Ask the person for the code they received and try again. | Do not retry automatically |
DIGILOCKER_SESSION_EXPIRED | 422 | The DigiLocker session has expired. Start a new session. | Do not retry automatically |
FLOW_INVALID | 422 | The flow cannot be saved or run as it stands. See the listed problems. | Do not retry automatically |
OCR_DOCUMENT_TYPE_MISMATCH | 422 | The document is not the type this product reads. | Do not retry automatically |
OCR_INPUT_CORRUPT | 422 | The document could not be decoded. | Do not retry automatically |
OCR_LOW_CONFIDENCE | 422 | The document could not be read with enough confidence. Retry with a clearer image. | Safe to retry |
OCR_PAGE_LIMIT_EXCEEDED | 422 | The document has more pages than this product accepts. | Do not retry automatically |
OCR_UNREADABLE | 422 | No text could be found in the document. Retry with a clearer image. | Safe to retry |
SANDBOX_FIXTURE_MISSING | 422 | No sandbox fixture exists for this input. Use a different test value. | Do not retry automatically |
UPSTREAM_REJECTED | 422 | The upstream source rejected the input. | Do not retry automatically |
VALIDATION_FAILED | 422 | The request payload is invalid. | Do not retry automatically |
CONCURRENCY_LIMIT | 429 | Too many simultaneous requests. | Safe to retry |
FLOW_GRANT_EXHAUSTED | 429 | That flow grant has no uses left. | Do not retry automatically |
FLOW_RUN_LIMIT_REACHED | 429 | Too many flow runs are active. | Safe to retry |
OCR_QUEUE_SATURATED | 429 | The document queue is full. Retry shortly. | Safe to retry |
PLAYGROUND_GRANT_EXHAUSTED | 429 | That playground grant has no uses left. | Do not retry automatically |
QUOTA_EXCEEDED | 429 | The allowance for this window is spent. | Do not retry automatically |
RATE_LIMITED | 429 | Too many requests. | Safe to retry |
INTERNAL_ERROR | 500 | An unexpected error occurred. | Safe to retry |
OUTCOME_UNCERTAIN | 502 | The outcome of this request is not yet known. Retry with the same Idempotency-Key. | Do not retry automatically |
UPSTREAM_UNAVAILABLE | 502 | The upstream source is unavailable. Retry shortly. | Safe to retry |
MAINTENANCE_MODE | 503 | The service is in a maintenance window. | Safe to retry |
NO_PROVIDER_AVAILABLE | 503 | No provider can serve this product right now. | Safe to retry |
OCR_UNAVAILABLE | 503 | Document reading is unavailable right now. Retry later. | Safe to retry |
SERVICE_OVERLOADED | 503 | The service is shedding load. Retry shortly. | Safe to retry |
OCR_TIMEOUT | 504 | The document took too long to process. Retry shortly. | Safe to retry |
UPSTREAM_TIMEOUT | 504 | The 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.