Errors

HTTP errors

Every error response carries a code and a detail:

{ "code": "resets-exhausted", "detail": "A human-readable message." }

Branch on code. Several causes share a status - 409 alone covers nine of them - so the status tells you the kind of failure and the code tells you which one. detail is written for a person reading a log: it names the workflow, verification, step or field at fault, and its wording is not stable. Treat a code you do not recognise as the status it arrived at. Codes are added as new causes become reachable, and an existing one never changes meaning, so a default branch on the status is always a safe fallback.

Status	When
`400`	The `workflow_key` names no workflow of yours; `context` omits a field the workflow’s required steps cannot run without, or supplies one in a shape the step that reads it cannot use; a hosted workflow was created without a `mobile`, or with a `return_url` that is not on the workflow’s allowlist; or a staged workflow was created with a `mobile` or a `return_url`, which it takes neither of. Also a document upload whose multipart body could not be read.
`401`	The `Authorization` header is missing, malformed, or the API key was rejected.
`402`	One of the workflow’s two balances is empty. Its credits: none were ever granted, or its verifications have used them, their term has passed, or we have taken them back, so nothing on it can be created or moved along until it is topped up. Or its resets: clearing a verification that had not ended re-runs its checks at nobody’s expense, and the workflow has none left to pay for that. Everything on it stays readable either way. Read the code to tell which. See Credits and limits.
`403`	The API key is for the other environment from the workflow or record you named. Or the key is valid but not enrolled as a verification client, or not set up for exactly one of `uat` and `production`. See Environments.
`404`	No verification with that id for you, no document with that id on it, or no step by that key on the version of the workflow it runs. Also a path this API does not serve.
`405`	The path is one this API serves, but not by that method.
`409`	The verification’s status, the workflow’s mode, or its live ceiling forbids what you asked. Nine codes answer here and each clears differently, so read the code: see Every code and Retrying safely.
`413`	An uploaded file is larger than the step accepts.
`415`	An uploaded file is of a type the slot does not take.
`422`	The request body failed validation (a malformed phone, a missing field), an id in the path is not a valid UUID, a document was sent for a step that takes none, or a staged submission cannot be run as it stands: a value is not valid, a required step has nothing, a slot is only part filled, a document names no kind where its slot asks for one or a kind that slot does not name, or a step was given both values and a document.
`429`	The API key is rate limited. Pause and retry.
`500`	The workflow’s configuration is faulty. Contact us; nothing about your request was wrong.
`503`	API keys could not be checked right now. Retry.

On 422, detail names each field at fault and what was wrong with it, separated by ; when more than one failed:

{
  "code": "request-invalid",
  "detail": "mobile: String should match pattern '^(?:\\+91)?[6-9][0-9]{9}$'"
}

Every code

Code	Status	What it means
`unauthenticated`	`401`	The `Authorization` header is missing or malformed, or the API key was rejected.
`client-not-enrolled`	`403`	The key is valid but not enrolled as a verification client, or not set up for exactly one of `uat` and `production`. Ask us to reissue it.
`environment-mismatch`	`403`	The key is for the other environment from the workflow or record you named. See Environments.
`rate-limited`	`429`	The key is rate limited. Pause and retry the same request.
`auth-unavailable`	`503`	Keys could not be checked right now. Retry the same request.
`workflow-not-found`	`400`	No workflow of yours carries that `workflow_key`.
`workflow-version-not-found`	`404`	The workflow has published no version with the number in the path.
`context-incomplete`	`400`	On a create that starts a verification, `context` omits a field the required steps of the workflow’s latest version cannot run without, or, on a reset, the latest version reads one the verification was not created with. The detail names each one.
`context-value-invalid`	`400`	`context` supplies a field in a shape the step that reads it cannot use, on a create that starts a verification or on a reset, either way against the workflow’s latest version. The detail names each one.
`mobile-required`	`400`	A hosted workflow was created without a `mobile`, which its user signs in with.
`journey-fields-refused`	`400`	A `mobile` or a `return_url` was given to a workflow that takes neither.
`return-url-not-allowed`	`400`	The `return_url` is not on the workflow’s allowlist.
`body-unreadable`	`400`	A document upload’s multipart body could not be read: malformed parts, or parts that do not match the boundary the `Content-Type` declares. Nothing was stored.
`credits-exhausted`	`402`	The workflow has no prepaid credits left. See Credits and limits.
`resets-exhausted`	`402`	The workflow has no resets left, and the verification you are clearing was never charged for. Resets are sold with credits; top up to get more. See Credits and limits.
`verification-not-found`	`404`	No verification with that id on your account.
`step-not-found`	`404`	The version of the workflow the verification runs declares no step by that key.
`document-not-found`	`404`	No document with that id is on the verification.
`not-found`	`404`	No endpoint at that path.
`method-not-allowed`	`405`	That path is served, but not by the method you used.
`reference-taken`	`409`	The `reference_user_id` already belongs to a different user in that workflow.
`verification-not-open`	`409`	The verification’s status forbids the action: cancelling one already submitted, or supplying a run that has ended.
`verification-expired`	`409`	The verification’s data has been deleted, so there is nothing to act on. Create a new one for that subject.
`workflow-not-runnable`	`409`	The workflow’s mode forbids the action: creating an `instant` verification, or resetting one.
`workflow-not-walkable`	`409`	The workflow’s mode forbids the action: handing off into a workflow that is not hosted, or uploading to one that is not staged.
`run-in-progress`	`409`	The checks have been asked to run, which freezes the submission until a reset.
`step-not-ready`	`409`	The step is not in a state where the request makes sense: it is still enriching, or it has already passed.
`live-limit-reached`	`409`	The workflow holds as many verifications `open` or `submitted` as it may. A place frees when one ends. See Credits and limits.
`document-not-stored`	`409`	The document was read in the request that carried it and kept nowhere, so there is no file to link to.
`request-too-large`	`413`	The request is larger than one may carry.
`document-too-large`	`413`	An uploaded file is larger than the step accepts.
`document-type-not-allowed`	`415`	An uploaded file is of a type the slot does not take.
`request-invalid`	`422`	The body, a path identifier or a query parameter failed validation. The detail names each field at fault.
`page-cursor-invalid`	`422`	The `cursor` did not come from a page of this list. Start from the first page again rather than constructing one.
`window-invalid`	`422`	The period asked for runs backwards: `from` is after `to`.
`step-invalid`	`422`	The submission cannot be run as it stands: a required step with nothing, a slot part filled, a value that is not valid, or a document a step does not take.
`workflow-misconfigured`	`500`	The workflow’s configuration is faulty, such as a gate check with no checks endpoint registered to ask it at, one whose fallback redirects to a link the workflow’s return URLs do not allow, or an output transformation that cannot convert a value a verification holds, whose record then cannot be read. Contact us; nothing about your request was wrong.
`internal-error`	`500`	Something failed on our side. Retry, and contact us if it persists.

Step reason codes

A step that did not pass carries reasons, each a stable code with a message written for the user’s screen. Branch on the code; the message wording can change. A step whose judgement turns on several checks reports one code for each check that did not hold, so read the whole array rather than its first entry. While the verification is open, a user can clear most of these by answering the step again, and you can clear them on a staged verification by resetting and running again. Once it reads completed, a failed step stays failed unless you reset the verification, so the code is what to base your own decision on.

Code	Step type	Means
`documents-missing`	`documents`, `parsed-documents`, `address-proof`	A slot still needs files: one that is required, or an optional one that already holds some.
`documents-unacceptable`	`documents`, `parsed-documents`, `address-proof`, `pcb-certificate`	The files in a slot are not a set it takes: a mix of file types, more files than it accepts, or a kind the slot no longer names.
`reading-unreadable`	`parsed-documents`	A slot’s files could not be read as the document they were provided as.
`check-expiry-unmet`	`parsed-documents`	The document had already expired on the day the step was judged.
`check-name-unmet`	`parsed-documents`	The name on the document does not match any name the step was given to compare it with.
`check-code-unmet`	`parsed-documents`	The identifier on the document is not the one the step was given to compare it with.
`premises-photos-missing`	`premises-photos`	A photo the step asks for still needs shots.
`address-tags-missing`	`address-tagging`	An address the step presents has not been tagged.
`address-proof-unreadable`	`address-proof`	No premises address could be read from a slot’s document.
`address-proof-unverified`	`address-proof`	The documents did not evidence as many of the given addresses as the step requires.
`address-proof-not-checkable`	`address-proof`	The step was given no address to check the documents against, so nothing about them could be judged.
`address-proof-wrong-kind`	`address-proof`	A slot’s document is not the kind it was provided as. The address it carries stands nothing up, whatever it matches.
`pan-card-missing`	`pan-card`	No card image is on the step.
`pan-unreadable`	`pan-card`	The card image could not be read.
`pan-registry-unconfirmed`	`pan-card`	The income-tax registry would not confirm the details read off the card.
`pan-inactive`	`pan-card`	The card’s PAN is not active with the income-tax registry.
`pan-mismatch`	`pan-card`	The card carries a different PAN from the one the step expected.
`pan-not-linked-to-gstin`	`pan-card`	The card’s PAN is not the one the step’s GSTIN is registered to.
`pan-holder-not-listed`	`pan-card`	The card is not in the name of any of the people the step listed.
`gst-certificate-missing`	`gst-certificate`	No certificate is on the step.
`gst-unreadable`	`gst-certificate`	The certificate could not be read.
`gst-gstin-mismatch`	`gst-certificate`	The certificate is for a different GSTIN from the one the step was given.
`gst-pan-mismatch`	`gst-certificate`	The certificate’s GSTIN is not registered to the PAN the step was given.
`gst-not-registered`	`gst-certificate`	The GSTIN read off the certificate was rejected by the GST registry as invalid.
`gst-inactive`	`gst-certificate`	The registry knows the GSTIN, but the registration is neither active nor active pending verification: cancelled, suspended, or otherwise not in force.
`gst-constitution-mismatch`	`gst-certificate`	The registry holds the registration under a different constitution of business from the one the step was given.
`gst-pages-missing`	`gst-certificate`	Fewer pages of the certificate were provided than the step accepts as a complete set.
`gst-pages-unacceptable`	`gst-certificate`	The certificate files are not one complete set: a PDF mixed with photos, or more files than the step accepts.
`gst-promoters-missing`	`gst-certificate`	The certificate pages provided do not include the one listing the proprietor, partners or directors.
`udyam-certificate-missing`	`udyam`	No Udyam registration certificate is on the step.
`udyam-unreadable`	`udyam`	The certificate could not be read.
`udyam-not-registered`	`udyam`	The number read off the certificate is not in the Udyam registry.
`udyam-inactive`	`udyam`	The registry knows the number, and the registration behind it has been cancelled.
`pcb-certificate-missing`	`pcb-certificate`	No certificate is on the step.
`pcb-unreadable`	`pcb-certificate`	The certificate could not be read.
`pcb-expired`	`pcb-certificate`	The consent’s validity period ended before the day the step was judged.
`pcb-name-mismatch`	`pcb-certificate`	The certificate was issued to a name far enough from every name the step holds it to that it is a different business.
`pcb-not-checkable`	`pcb-certificate`	The step holds the certificate to a list of names, and the list it was given was empty, so there was no name to check the certificate against.
`name-mismatch`	`name-match`	A checked name is too far from the reference to be the same name.
`bank-proof-missing`	`bank-account`	The document intake was chosen but no document is on the step.
`bank-proof-unreadable`	`bank-account`	The account details could not be read off the document.
`bank-account-unverified`	`bank-account`	The bank did not confirm the account number and IFSC.
`bank-name-mismatch`	`bank-account`	The account is registered to none of the names the step expects it to be in.
`selfie-missing`	`selfie`	No selfie is on the step.
`selfie-unreadable`	`selfie`	The selfie could not be read, so no check ran over it.
`selfie-not-live`	`selfie`	The liveness check did not hold; the capture did not read as a live subject.
`selfie-face-mismatch`	`selfie`	The face in the selfie is not the one on the identity document the step matches it against.
`digilocker-session-expired`	`digilocker`	The consent session no longer exists; the user has to consent again.
`digilocker-documents-missing`	`digilocker`	The user did not consent to every document the workflow requires.
`digilocker-pan-mismatch`	`digilocker`	The account holder shared a PAN, and it is not the one the step expected.
`digilocker-pan-unreadable`	`digilocker`	The PAN document was shared, but without a PAN number that could be read off it, and the workflow requires the PAN.
`digilocker-holder-not-listed`	`digilocker`	The account holder is not one of the people the step listed.
`could-not-verify`	any step with a check	The check could not be completed. On an `error` step this is the one code that is not worth waiting on: the check is not attempted again, and a reset is what runs it afresh.
`vendor-unavailable`	any step with a check	The source could not be reached this time. The check is attempted again on its own, except on a gate check: there your system gave no answer, the workflow holds the person on the step, and the check is asked again only when their journey tries it again.
`check-not-attempted`	any step with a check	The check was never made, because the run had spent its time before reaching it. It is what an instant run that runs long leaves on the checks it did not get to, each of which reads `error`. See Instant.
`gate-check-faulted`	`gate-check`	The check could not be asked because of a fault on our side: your endpoint refused the request, your auth service refused the registered credentials, or nothing is registered to ask it at. The person is held on the step, and each try asks the check again.
`check-cancelled`	any step with a check	The verification ended, whether cancelled, stopped by a gate check, marked failed or expired, while this check was still being made, so it was never finished and never will be. Where the verification can be reset, a reset runs it afresh.

Step gap codes

A step that passed can carry gaps: optional pieces it asked for that never arrived. A gap takes the same shape as a reason, a stable code with a message written for the user’s screen, and says what the record is missing rather than that anything failed. A step reporting one of these passed.

Code	Step type	Means
`check-expiry-reported`	`parsed-documents`	The document is still valid but expires within the warning window the step asks about. The step passed and reports how long is left, so a document about to run out is seen before it does.
`check-name-reported`	`parsed-documents`	The name on the document is similar to one the step was given but below the matching threshold. The step passed and reports the score, so a near miss is left for a person to weigh.
`gst-pending-verification`	`gst-certificate`	The registry holds the registration as active pending verification: in force, but not yet verified by the GST department. The step passed and reports it, so a registration still under review is left for a person to weigh.
`digilocker-document-missing`	`digilocker`	A document the workflow asks for but does not require was not shared from the user’s DigiLocker.
`digilocker-pan-unreadable`	`digilocker`	The PAN document was shared, but without a PAN number that could be read off it. The workflow does not require the PAN, so the step passed and publishes no `pan`.
`name-match-inexact`	`name-match`	A checked name is close to the reference but below the matching threshold. The step passed and reports the score, so a near miss is left for a person to weigh.
`pcb-name-inexact`	`pcb-certificate`	The name the certificate was issued to is close to the nearest of the names the step holds it to but below the matching threshold. The step passed and reports the score, so a near miss is left for a person to weigh.
`gate-check-unanswered`	`gate-check`	Your system did not answer the check, so the step took the fallback your workflow declares in `when_unanswered`. `details.cause` says why: `unreachable` or `unreadable`, as Step types describes.
`gate-check-redirect-refused`	`gate-check`	A redirect could not send the person on, because its link was missing or is not on the workflow’s list, so the journey ended as `terminate` ends it. `details.cause` is `no-link` or `not-allowed`.

Retrying safely

Reads (GET) change nothing, so they are safe to poll and retry.
Create is idempotent per subject and workflow, so retrying POST /verifications never creates a duplicate. It answers 201 when the call created the verification and 200 when it resolved to one you already had.
Run the checks is idempotent on the same values: repeating the request names the run already in progress and changes nothing. Different values are refused with 409 until you reset.
Run it now (POST /verifications/instant) is not idempotent, and it is the one call where a blind retry costs you. Every call is a new verification answered on what that call carried, and a new credit. A call that times out was still run and still charged, so look for its record by reference_user_id before sending the submission again. See Instant.
Cancel and purge are idempotent; repeating either on a verification already in that state succeeds.
429 and 503 are transient. Back off and retry the same request.

A 409 is not transient, and it is the status where the code earns its keep: nine codes answer at it, and what to do next differs for each.

Code	What clears it
`verification-not-open`	Nothing on this record. Act on one in the right state, or reset this one.
`verification-expired`	Nothing. Create a new verification for that subject.
`workflow-not-runnable`, `workflow-not-walkable`	Nothing. The workflow’s mode does not do this; use the call its mode takes.
`run-in-progress`	Reset the verification, which is the only way to change a frozen submission.
`reference-taken`	Use a `reference_user_id` not already in that workflow.
`live-limit-reached`	One of your verifications ending. `runs.live` against `runs.limit` says how close you are.
`step-not-ready`	Waiting, where the step is still enriching. Where it has already passed, nothing: reset the verification to run it again.
`document-not-stored`	Nothing. The file was read in the request that carried it and kept nowhere, so there is no link to give.

A 402 is not transient either, and it is the one refusal you cannot clear yourself. The same call is refused until the workflow is topped up, so surface it rather than retrying it. credits-exhausted and resets-exhausted are both topped up by buying, but they are not the same purchase: read the code before asking us for more of the wrong thing. See Credits and limits.

Get started

Run a verification

Read the result

Go live

Reference

HTTP errors

Every code

Step reason codes

Step gap codes

Retrying safely

​HTTP errors

​Every code

​Step reason codes

​Step gap codes

​Retrying safely

HTTP errors

Every code

Step reason codes

Step gap codes

Retrying safely