Error Handling

Error Response Format

All errors return a consistent JSON format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "request_id": "abc123"
  }
}

Error Codes

HTTP Status	Code	Description
400	INVALID_VAT_ID	VAT ID format is invalid
401	UNAUTHORIZED	Missing or invalid API key/token
403	EMAIL_NOT_VERIFIED	Email not yet verified
404	NOT_FOUND	Endpoint or resource not found
409	CONFLICT	Email already registered
429	RATE_LIMITED	Rate limit exceeded
500	INTERNAL_ERROR	Unexpected server error
503	SOURCE_UNAVAILABLE	All upstream validation sources down

Rate Limit Headers

When rate limited (429), the response includes:

• Retry-After - Seconds until you can retry
• X-RateLimit-Remaining - Always 0 when limited
• X-RateLimit-Reset - Unix timestamp when the limit resets