Error Handling

VerifyHQ uses conventional HTTP status codes. All errors include a structured JSON response.

Error Format

Error Responsejson

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Front image is required. Please upload a clear photo of the front of your document.",
  "timestamp": "2025-01-15T10:30:00Z"
}

HTTP Status Codes

Parameter	Type	Description
`200`	Success	Request succeeded
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid request body or missing required fields
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for this operation
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource already exists (e.g., active verification)
`413`	Payload Too Large	File exceeds 10MB limit
`422`	Unprocessable	Validation failed (see message for details)
`429`	Rate Limited	Too many requests. Check Retry-After header.
`500`	Server Error	Internal error. Contact support if persistent.
`503`	Unavailable	Service temporarily unavailable

Validation Errors

422 Validation Errorjson

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": [
    "Country code must be uppercase ISO 3166-1 alpha-2 (e.g., US, GB, NG)",
    "Document type must be one of: ID_CARD, PASSPORT, DRIVER_LICENSE, RESIDENCE_PERMIT"
  ]
}

Retry Strategy

For 429 and 503 errors, use the Retry-After header value. For 500 errors, retry with exponential backoff up to 3 times.