Skip to main content

​
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

CodeHTTP StatusDescription
missing_parameter400Required query parameter vat_number not provided
invalid_vat_format422VAT number format unrecognized or country code unsupported
unauthorized401Invalid or missing API key
rate_limit_exceeded429Monthly quota exhausted
burst_limit_exceeded429Per-minute burst limit exceeded
upstream_unavailable503Upstream service (VIES, HMRC, BFS, BRREG, or ABR) is unreachable or returned an error
tier_insufficient403Feature requires a higher tier (e.g. batch validation on Free)
validation_error422Request body validation failed (e.g. batch endpoint)
invalid_json400Request body contains malformed JSON
not_found404Requested resource not found (e.g. unknown country code for rates)
forbidden403Access to this resource is forbidden (e.g. demo key restriction)
key_limit_reached403Maximum number of API keys reached for this account
key_revoked409The API key has already been revoked
internal_error500An unexpected server error occurred
upstream_member_state_unavailable503Specific EU member state VIES service is unavailable
webhook_not_configured400No webhook URL configured for async validation

​
Handling errors with the SDKs

The @vatly/node and vatly (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 Vatly, {
  RateLimitError,
  UpstreamError,
  AuthenticationError,
  ValidationError,
  VatlyError,
} from "@vatly/node";

const vatly = new Vatly("vtly_live_your_api_key");
const { data, error } = await vatly.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 {
    // VatlyError base class
    console.log(`${error.code}: ${error.message}`);
    console.log(error.docsUrl);
  }
}
Every error has code, message, and docsUrl (Node.js) / docs_url (Python) properties matching the error codes above.