Errors

HTTP, SDK, and webhook errors with safe recovery guidance.

Error bodies can gain fields over time. Branch on the HTTP status and a documented machine-readable code when present.

HTTP errors

Status	Typical cause	Retry?	Recommended action
400	Invalid JSON, field, enum, date, identifier, or webhook signature	After correction	Validate the request against the endpoint reference
401	Missing or invalid API key or session token	No blind retry	Check credential injection, token age, and environment
404	Unknown refId, flow, case, or resource	Usually no	Confirm the environment and identifier
429	Rate limit exceeded	Yes	Use bounded backoff
5xx	VOVE ID or upstream service failure	For idempotent work	Retry with bounds and stable identifiers

Client integration failures

Symptom	Check	Recovery
SDK initialization fails	Environment, public key, and approved client configuration	Correct configuration and initialize again
Session token is rejected	Environment, token age, accidental modification	Request a new token from your backend
Camera is unavailable	Permission, browser/device support, another app using the camera	Explain how to grant access or switch device
Capture fails repeatedly	Glare, blur, framing, unsupported document, wrong flow step	Provide capture guidance without exposing fraud rules
Maximum attempts reached	Attempt policy	Stop retry loops and offer the approved support path

Safe diagnostics

Log the environment, endpoint name, HTTP status, request/correlation ID, refId or case ID when permitted, SDK name/version, and timestamps.

Never log API keys, session tokens, webhook secrets or signatures, document images, biometric media, raw webhook payloads, or unredacted personal data.