DocsError reference
Error reference
HTTP status codes and JSON error shapes.
Every error response follows a consistent JSON shape. Parse the error field for machine-readable codes and message for human-readable detail.
JSON — Error shape
{
"error": "validation_failed",
"message": "documentImage must be a valid base64 string",
"details": [
{ "field": "documentImage", "issue": "Invalid base64 encoding" }
],
"requestId": "req_01J8KX9QMN23PQRST"
}| Status | Error code | Meaning | Fix |
|---|---|---|---|
| 400 | validation_failed | Request body failed schema validation | Check details[] for failing fields |
| 401 | unauthorized | Missing or malformed Authorization header | Supply a valid Bearer token |
| 403 | forbidden | Key lacks permission for this endpoint | Check API key scopes in the Console |
| 404 | not_found | Resource (check, report) does not exist | Verify the checkId or path |
| 409 | duplicate_check | Idempotency key already used | Use a new Idempotency-Key header |
| 422 | unprocessable_entity | Image quality too low for analysis | Retry with a clearer document/selfie image |
| 429 | rate_limit_exceeded | Requests-per-minute ceiling hit | Back off and retry after X-RateLimit-Reset |
| 500 | internal_error | TrustVerify-side failure (triggers Sentry alert) | Safe to retry with exponential backoff; contact support if persistent |
| 503 | service_unavailable | Planned maintenance or provider outage | Check status.trustverify.co.uk |
4xx errors are tenant-fixable — inspect your request. 5xx errors are TrustVerify-side — implement exponential backoff (1s, 2s, 4s…) and retry up to 3 times before alerting. All 5xx events trigger a Sentry alert on our side automatically.