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
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, or the API key belongs to a different EverAPI product.

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

# 422

Validation error, please check the list of validation errors: here

# 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

The VAT validation service of the requested country is currently not available. You can retry the request at any point to check again.

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).

# 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 →