Error Reference

Every error response includes a machine-readable code, a human-readable message, and a docs_url linking to the relevant page below. Errors from validation endpoints also echo the normalized vat_number you submitted (and requester_vat_number when supplied), so your logs always record which number an attempt was for.

{
  "error": {
    "code": "invalid_vat_format",
    "message": "The VAT number format is invalid. Expected format: CC123456789",
    "docs_url": "https://docs.avatcado.com/errors/invalid_vat_format",
    "vat_number": "DE123"
  },
  "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_unavailable`	503	Upstream service (VIES, HMRC, BFS, BRREG, or ABR) is unreachable or returned an error
`tier_insufficient`	403	Feature requires a higher tier (e.g. batch validation on Free)
`validation_error`	422	Request body validation failed (e.g. batch endpoint)
`invalid_json`	400	Request body contains malformed JSON
`not_found`	404	Requested resource not found (e.g. unknown country code for rates)
`forbidden`	403	Access to this resource is forbidden (e.g. demo key restriction)
`key_limit_reached`	403	Maximum number of API keys reached for this account
`key_revoked`	409	The API key has already been revoked
`internal_error`	500	An unexpected server error occurred
`upstream_member_state_unavailable`	503	Specific EU member state VIES service is unavailable
`webhook_not_configured`	400	No webhook URL configured for async validation

Handling errors with the SDKs

The @avatcado/node and avatcado (Python) SDKs provide typed error classes so you can match on specific error types. The Node.js SDK returns { data, error } from every method, while the Python SDK raises exceptions.

import Avatcado, {
  RateLimitError,
  UpstreamError,
  AuthenticationError,
  ValidationError,
  AvatcadoError,
} from "@avatcado/node";

const avatcado = new Avatcado("avat_live_your_api_key");
const { data, error } = await avatcado.vat.validate({ vatNumber: "NL123456789B01" });

if (error) {
  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof UpstreamError) {
    console.log(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof AuthenticationError) {
    console.log(error.message);
  } else if (error instanceof ValidationError) {
    console.log(error.message);
    console.log(error.details); // Array<{ field, message }> | null
  } else {
    // AvatcadoError base class
    console.log(`${error.code}: ${error.message}`);
    console.log(error.docsUrl);
  }
}

from avatcado import Avatcado, RateLimitError, UpstreamError, AuthenticationError, ValidationError, AvatcadoError

avatcado = Avatcado("avat_live_your_api_key")

try:
    result = avatcado.vat.validate("NL123456789B01")
except RateLimitError as e:
    print(f"Retry after {e.retry_after} seconds")
except UpstreamError as e:
    print(f"Retry after {e.retry_after} seconds")
except AuthenticationError as e:
    print(e.message)
except ValidationError as e:
    print(e.message)
    print(e.details)  # list of dicts or None
except AvatcadoError as e:
    print(f"{e.code}: {e.message}")
    print(e.docs_url)

Every error has code, message, and docsUrl (Node.js) / docs_url (Python) properties matching the error codes above. Errors from validation endpoints additionally carry the echoed vat_number and, when supplied, requester_vat_number; upstream 503 errors also carry meta.validation_id referencing the recorded attempt.