vatcheckapi.com Documentation

# Request Status Codes

For all requests, we will return an HTTP status code that indicates a success or the problem that has led to the failure.

A successful request will be returned with status code 200

# Error Response Body

Error responses are JSON objects with the following fields:

Field Presence Description
message always A human-readable description of the error
errors 422 only An object mapping each invalid parameter to an array of validation messages. Not sent when VIES rejected the input or for Invalid VAT number.
info 422 only A sentence containing a deep link to the matching section of this page, e.g. For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422. Sent alongside errors on 422 responses raised by request validation (e.g. a missing vat_number); other errors omit it
error 401, 403, 404, 429 An object with a stable machine-readable code (e.g. invalid_api_key, quota_exceeded) and the same human-readable message
actions 401, 403, 404, 429 An object of suggested next steps as URLs, e.g. upgrade and docs
quota quota 429 only The current quota state: limit, used, remaining and resets_at; plus required (the request's cost) when a request that costs more than your quota allows is refused before it runs
{
    "message": "Validation error",
    "errors": {
        "vat_number": [
            "The vat number field is required."
        ]
    },
    "info": "For more information, see documentation: https://vatcheckapi.com/docs/status-codes#_422"
}

# API Error Codes

# 401

The request is not authenticated: no API key was sent (No API key found in request) or the key is invalid (Unauthorized).

# 403

You are not allowed to make this request — for example, the request's referrer is not on your API key's referrer whitelist (referrer_not_allowed), or the API key belongs to a different EverAPI product (key_not_allowed_for_product).

A free account whose email address is not verified yet gets 5 requests. Once they are used up, requests are answered 403 with the code email_not_verified (instead of a 429), and actions.verify_email links to the verification. Click the link in the email we sent to the account owner; the full free quota then applies within 30 seconds.

An IBAN batch (opens new window) request answers 403 with the code plan_upgrade_required if your plan does not include batch requests.

If your plan does not include an endpoint (e.g. e-invoice validation (opens new window)), the error code is plan_upgrade_required and actions.upgrade links to the plans.

# 404

A requested endpoint does not exist

# 405

An HTTP method the endpoint does not take (error code method_not_allowed); the Allow header names those it does. A HEAD request answers 405 on every billed endpoint, without running it and without being billed; /v2/status and the other free endpoints answer HEAD like GET.

# 422

The request was rejected, see the list of validation errors. A 422 is not counted against your quota. For VAT checks (opens new window) it means one of:

  • a parameter is missing or invalid (vat_number, country_code or requester_vat_number),
  • VIES rejected the VAT number as invalid input,
  • VIES rejected your requester_vat_number.

A VAT number with an invalid format is not a 422: it is a 200 with format_valid: false and counts as a request.

# 429

You have hit your rate limit or your monthly limit. For more requests please upgrade your plan (opens new window).

An IBAN batch (opens new window) is checked against your remaining quota before it runs. If its cost would use up the remaining quota, it is refused, quota.required holds its cost, and nothing is processed or billed. The code names the quota that runs short: quota_exceeded (monthly quota), grace_quota_exceeded (grace quota after a failed payment) or overage_quota_exceeded (overage budget). Send fewer IBANs or upgrade your plan.

Every e-invoice (opens new window) request is checked against your remaining quota before it runs: 1 request for an XML file, 2 for a PDF. If the quota cannot pay for it, the API answers 429 with quota.required set to that amount, and nothing is processed or counted. The error code names the quota that runs short: quota_exceeded, grace_quota_exceeded or overage_quota_exceeded.

# 500

Internal Server Error - let us know: support@vatcheckapi.com

# 503

For VAT checks (opens new window) (/v2/check), VIES, the member state's register or the GB data service is not available, or did not answer within about 55 seconds. A 503 is not counted against your quota. Retry a little later. The VIES status endpoint (opens new window) shows for free which member states VIES can check right now.

For EORI checks (opens new window) (/v2/eori), the register for the number did not answer in time or is failing, or, for GB numbers, HMRC's rate limit (opens new window) is used up for the moment. When the response has a Retry-After header, retry after that many seconds (currently always 1); otherwise retry a little later. A 503 is not counted against your quota.

For e-invoice validation (opens new window), 503 means that the validation service is unavailable, busy or did not finish in time. The request is not counted; retry it later.

# Validation errors

# Missing vat_number

The vat_number parameter is required

# Missing country_code

The country_code parameter is required, if the given vat_number has no country code.

# Unsupported country_code

The given country_code (or the country prefix of the vat_number) is not one of the supported countries (opens new window). Case does not matter, and Greece is accepted as EL or GR.

# Invalid requester_vat_number

The requester_vat_number of /v2/check must be a string of at most 32 characters: an EU VAT number (the 27 member states or XI) with its country prefix, with a valid format and checksum. A GB number or a number without prefix is refused. The message names the problem, e.g. "The requester VAT number is not a valid AT VAT number." VIES is not asked.

# VIES rejected the input

VIES refused the request itself. The response contains only a message: "VIES rejected the VAT number as invalid input." or, for your requester_vat_number, "VIES rejected the requester VAT number. Check requester_vat_number." Sending the same request again gives the same answer.

# Missing or too long eori_number

The eori_number parameter of /v2/eori is required, must be a string and must not be longer than 64 characters. country_code, when sent, must be a string as well.

# Unsupported EORI country

The eori_number does not start with a supported country code (opens new window): it starts with another country's code (such as EL or US, also when country_code is sent), or it has none and country_code does not name a supported one. The message (under errors.country_code) lists the supported codes. Greece is GR in EORI numbers, not EL.

# Invalid VAT number

The given vat_number could not be validated. Unlike the parameter errors above, this response contains only a message ("Invalid VAT number.") and no errors object.

# Missing or invalid iban

The iban parameter of /v2/iban (opens new window) is required. It must be a string of at most 64 characters of valid UTF-8 text. A string that is not a valid IBAN is not an error: the response is a 200 with valid: false.

# Missing or invalid ibans

The ibans field of /v2/iban/batch (opens new window) is required and must hold at least one IBAN. Each entry must be a string of at most 64 characters of valid UTF-8 text; an invalid entry is reported under its position in the list as you sent it, counting from 0 (e.g. ibans.1 for the second entry), even when duplicates come before it.

# Too many IBANs

A batch can contain at most 100 IBANs, counted after normalisation (spaces removed, upper case) without duplicates, and at most 1,000 entries before that.

# IBANs in the query string

The batch reads ibans from the request body only. An ibans parameter in the query string is refused with the message "Send the IBANs in the request body, not in the query string."

# E-invoice: missing invoice

/v2/einvoice/validate got no file: send it as the request body (Content-Type: application/xml or application/pdf), as the multipart field file, or base64-encoded as the JSON property content_base64. The error is listed under file, or under content_base64 for a JSON request.

# E-invoice: not an XML or PDF file

The file sent to /v2/einvoice/validate is neither XML nor a PDF.

# E-invoice: file too large

The invoice is larger than 10 MB (after base64 decoding for JSON).

# E-invoice: invalid content_base64

content_base64 is not valid base64.

# E-invoice: invalid option

format must be one of auto, xrechnung, zugferd or en16931, language one of en or de, and filename, if sent, a string of at most 255 characters.

← Status Endpoint →