Errors

Every error has the same shape and a stable code. Switch on code; messages are neutral recovery guidance and may change.

Error shape

4xx / 5xxjson

{
  "code":      "BLINK_SESSION_INVALID",
  "message":   "Session is no longer valid",
  "timestamp": "2026-09-15T18:34:57Z"
}

API error codes

Code	HTTP	Meaning · what to do
`BLINK_CLIENT_MISSING`	400	Client credentials were not supplied.
`BLINK_CLIENT_AUTH_FAILED`	400	Client authentication failed. Check the key and secret.
`BLINK_SCOPE_DENIED`	400	The requested product is not enabled for your client.
`BLINK_REQUEST_REJECTED`	400 · 405 · 415	Unsupported request shape, method or media type.
`BLINK_SESSION_INVALID`	401	Token missing, invalid or expired. Create a new session.
`BLINK_ORIGIN_NOT_ALLOWED`	403	The browser origin isn't allowed. Register it.
`BLINK_SESSION_NOT_FOUND`	400	The session is no longer available.
`BLINK_SESSION_EXPIRED`	400	The session expired mid-flow. Create a new one.
`BLINK_SESSION_SPENT`	400	The session already finished. Create a new one.
`BLINK_CHALLENGE_INVALID`	400	Nonce unknown, reused or expired. Fetch a fresh challenge.
`BLINK_STEP_OUT_OF_SEQUENCE`	400	Liveness attempted before the document step.
`BLINK_STEP_INCOMPLETE`	400	Finalize called before all required steps.
`BLINK_STEP_ALREADY_DONE`	400	That step already completed.
`BLINK_STEP_NOT_IN_PURPOSE`	400	The step isn't part of the session's purpose.
`BLINK_UNKNOWN_DOCUMENT_TYPE`	400	`documentType` is not a supported value.
`BLINK_UNKNOWN_DOCUMENT_SIDE`	400	The document side is unsupported.
`BLINK_UPLOAD_REJECTED`	400 · 413	The capture was not accepted (e.g. too large).
`BLINK_UPLOAD_UNREADABLE`	400	The capture could not be read.
`BLINK_RESULT_NOT_FOUND`	404	Unknown session, another client's session, or wrong credentials.
`BLINK_QUOTA_EXCEEDED`	429	Your plan's quota is used up.
`BLINK_TEMPORARILY_UNAVAILABLE`	503	Retryable interruption. Retry with backoff.
`BLINK_REQUEST_FAILED`	500	The request failed. Retry once, then contact Blink.

Step outcomes

Returned as HTTP 200 on the device calls, and raised by the SDKs as BlinkStepError:

Code	What to do
`DOCUMENT_ACCEPTED`	Nothing — the step passed.
`DOCUMENT_UNREADABLE`	Ask for a retake in better light, with a new session.
`LIVENESS_ACCEPTED`	Nothing — the step passed.
`LIVENESS_FAILED`	Offer another attempt with a new session.
`LIVENESS_CHALLENGE_INVALID`	The liveness challenge expired. Start again.

SDK-only codes

Raised on the device as BlinkError with httpStatus 0:

Code	What to do
`BLINK_NETWORK` · `BLINK_TIMEOUT`	Connectivity. Let the customer retry.
`BLINK_CAMERA_DENIED`	Explain why the camera is needed and link to Settings.
`BLINK_CAPTURE_CANCELLED`	The customer closed the camera. Not an error to report.
`BLINK_CONFIG`	Invalid SDK setup, e.g. a malformed base URL or hosted link.

Rate limits

A 429 carries Retry-After (seconds) and X-RateLimit-Remaining headers. Wait for Retry-After before retrying.