> For the complete documentation index, see [llms.txt](https://docs.voveid.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.voveid.com/docs/api-fundamentals/errors.md).

# 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.