Error Reference

All Vatly API error codes at a glance

Error Reference

Every error response includes a machine-readable code, a human-readable message, and a docs_url linking to the relevant page below.

{
  "error": {
    "code": "invalid_vat_format",
    "message": "The VAT number format is invalid. Expected format: CC123456789",
    "docs_url": "https://docs.vatly.dev/errors/invalid_vat_format"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

All error codes

Code	HTTP Status	Description
missing_parameter	400	Required query parameter vat_number not provided
invalid_vat_format	422	VAT number format unrecognized or country code unsupported
unauthorized	401	Invalid or missing API key
rate_limit_exceeded	429	Monthly quota exhausted
burst_limit_exceeded	429	Per-minute burst limit exceeded
upstream_error	503	HMRC returned an unexpected error
upstream_unavailable	503	VIES or HMRC is unreachable