Error reference.
Every error the API can return, what it means, and the exact fix.
Every failing request from the vatverify API returns a stable error.code string alongside a human-readable error.message. Codes are versioned and never renamed, so you can branch on them in your integration without worrying about breakage on minor releases.
The codes fall into four groups: input validation ( invalid_format, malformed VAT numbers), registry state (registry_unavailable, country-level outages), account and plan limits (rate_limited, plan_required), and business rules (seller_country_unsupported, b2c_not_supported). Each has a different retry strategy: transient registry errors should retry with backoff, validation errors should surface to the user, and plan errors should link to upgrade.
Each entry below links to a dedicated page with the exact trigger condition, a JSON response sample, the recommended client-side handling, and any related webhook events. Use this reference when mapping API responses to UX states in your checkout, onboarding, or tax engine flows.
- b2c_not_supportedThe /decide endpoint only handles B2B transactions. B2C is not supported in v1.
- batch_too_largeThe vat_numbers array contains more than 50 items.
- buyer_vat_not_registeredThe buyer_vat number passed to /decide is invalid or not registered with the registry.
- bzst_rejectedBZSt returned an unrecognised status code that does not map to a typed vatverify error.
- bzst_server_errorBZSt accepted the request but returned an internal server error (evatr-2004, evatr-2011, evatr-3011).
- bzst_session_limitThe API hit the per-session quota for qualified confirmations against BZSt (evatr-0008).
- bzst_unavailableBZSt is temporarily unreachable or returned a degradation status (evatr-0011, evatr-1001 through evatr-1004).
- country_unknownThe country code passed to the rates endpoint does not exist in the dataset.
- country_unsupportedThe VAT number's country prefix maps to a country that vatverify does not support.
- invalid_formatThe request body is malformed, a required field is missing, or a field has the wrong type.
- invalid_requester_vatThe requester_vat_number supplied to /v1/confirm is malformed or fails the MOD-11 checksum required for §18e qualified confirmations.
- not_foundYou are using a test-mode key and sent a VAT number that is not in the magic number registry.
- plan_requiredThe endpoint you called requires a higher plan than your current one.
- rate_limitedYour monthly quota of live registry calls has been exhausted.
- registry_unavailableThe upstream registry (VIES, HMRC, BFS, or Brønnøysund) returned an error or is temporarily down.
- seller_country_unsupportedThe seller_vat country prefix is not in EU-27. The /decide endpoint only supports EU sellers.
- unauthorizedThe API key is missing, malformed, or has been revoked.
- webhook_limit_reachedYou have reached the maximum of 5 registered webhook endpoints for this API key.