Errors

VeroID uses standard HTTP status codes and returns detailed error information in JSON format.

HTTP Status Codes

Error Response Format

{
  "error": "Error Type",
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "verificationId": "ver_..." 
}

Authentication Errors (401)

{
  "error": "Unauthorized",
  "message": "Missing API key. Include X-API-Key header."
}

Credit Errors (402)

{
  "error": "Payment Required",
  "message": "Insufficient credit balance. Please purchase more credits."
}

Sandbox Screening Errors (422)

Returned when a sandbox screening request uses a name that is not one of the predefined test triggers. The response includes testNames with the valid values. See Sandbox for the full list.

{
  "error": "Unprocessable Entity",
  "code": "SANDBOX_SCREENING_NAME_REQUIRED",
  "message": "Sandbox screening only accepts predefined test names...",
  "testNames": [
    "screenclear",
    "screensanction",
    "screenpep",
    "screenpossible",
    "screenmultiple",
    "screenmedia",
    "screenrca"
  ]
}

Access Errors (403)

Returned when a sk_live_* key is used before the onboarding fee is settled or before VeroID has approved your account for production DVS. This applies to every endpoint, including test-api.veroid.com.au. Use a sk_test_* key on the test endpoint until your account is approved for production.

{
  "error": "Forbidden",
  "message": "Live verification is locked until your account is approved for the production DVS hub. Use a test key against the test endpoint in the meantime."
}

If the onboarding fee is the blocker, the message names it instead:

{
  "error": "Forbidden",
  "message": "Live keys are issued once the one-time developer onboarding fee is paid. Use a sandbox key against the test endpoint in the meantime."
}

The API is only available to developer accounts. If the account has been switched to the dashboard track, its keys stop working entirely:

{
  "error": "Forbidden",
  "message": "API keys are not part of a dashboard account. Switch to a developer account to integrate over the API."
}

DVS Expanded Responses

A successful HTTP 200 from POST /v1/verify can still mean the document did not match. DVS expanded responses (field-level detail in the errors array) are not HTTP errors - they are part of a normal verification outcome when responseCode is N or D.

{
  "success": true,
  "responseCode": "N",
  "match": false,
  "errors": [
    { "source": "Issuer", "field": "BirthDate", "message": "Date of birth does not match." }
  ]
}

See Expanded Responses in the API reference. Do not retry N or D - only DVS system errors (S, or HTTP 500) are transient.

Rate Limits

When the per-key rate limit is exceeded, the API returns HTTP 429 with a Retry-After header (seconds).

Document cooldown (429)

On live verification, submitting the same document details again too soon returns HTTP 429 with code DOCUMENT_COOLDOWN - before the request reaches DVS. This protects against issuer lockouts when users retry quickly after a typo or failed check.

{
  "error": "Too Many Requests",
  "code": "DOCUMENT_COOLDOWN",
  "message": "This document was verified recently. Wait before submitting the same document again.",
  "retryAfterSeconds": 45
}

If DVS or the issuer has already locked the document, the cooldown is longer (about 5 minutes) and the message references a temporary DVS lock. Honour Retry-After and do not auto-retry with the same payload. See Best Practices.

DVS document lock (500)

When DVS returns "Document Temporarily Locked", the API responds with HTTP 500, code DVS_DOCUMENT_LOCKED, and a Retry-After header. Wait before submitting the same document details again - do not treat this like a system error (S) retry loop.

{
  "success": false,
  "error": "Verification Failed",
  "code": "DVS_DOCUMENT_LOCKED",
  "message": "Document Temporarily Locked",
  "verificationId": "ver_...",
  "retryAfterSeconds": 300
}