Error Codes

All error responses share the same JSON shape:

{
  "error": "invalid_policy_number",
  "message": "The policy number format is not recognised for the specified country.",
  "code": 400
}

HTTP status codes

Status	Meaning
200	Success
400	Bad request — invalid input
401	Unauthorised — missing or invalid API key
403	Forbidden — API key lacks permission for this operation
404	Not found — policy not found in registry
422	Unprocessable — request is well-formed but semantically invalid
429	Rate limit exceeded
500	Internal server error

Error codes

error value	Status	Description
invalid_policy_number	400	Policy number format not recognised for the specified country
missing_required_field	400	A required field (policy_number, country, or type) is absent
unsupported_country	400	Country code is not in the supported list
unsupported_insurance_type	400	Insurance type is not motor, travel, or health
unauthorized	401	Authorization header missing or key prefix invalid
invalid_api_key	401	API key not found or revoked
insufficient_credits	402	Verification credits exhausted for this billing period
insurer_not_found	404	Insurer not found in registry for the given country
policy_not_found	404	Policy number not found in registry
rate_limit_exceeded	429	Too many requests — see Rate Limits
internal_error	500	Unexpected server-side failure — retry with exponential backoff

Example: invalid API key

curl -X POST https://api.policynumbers.com/v1/verify \
  -H "Authorization: Bearer bad_key" \
  -H "Content-Type: application/json" \
  -d '{"policy_number":"DE-KFZ-88821","country":"DE","type":"motor"}'

{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid or has been revoked.",
  "code": 401
}

Example: rate limit exceeded

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your request limit. Retry after 47 seconds.",
  "code": 429,
  "retry_after": 47
}

When you receive a 429, check the Retry-After header and wait that many seconds before retrying. See Rate Limits for tier limits and backoff guidance.