​

Test Mode

​

How it works

• No upstream calls: Requests never reach VIES, HMRC, BFS, or Bronnysund
• No quota usage: Test requests don’t count toward your monthly limit
• No burst limit: Test keys are exempt from the per-minute burst limit
• No rate limit headers: Since there’s no quota or burst limit, rate limit headers are omitted
• Async endpoints reject test keys: /v1/validate/async and /v1/validate/async/batch return 403 forbidden for avat_test_ keys. Use a avat_live_ key for async testing
• No caching: Every request returns a fresh response
• Format validation still applies: Invalid VAT formats return invalid_vat_format just like in live mode
• meta.mode: "test": Every test response includes this field so you can distinguish test from live

​

Magic VAT numbers

​

Examples

curl -H "Authorization: Bearer avat_test_your_api_key" \
  "https://api.avatcado.com/v1/validate?vat_number=DE111111111"

import Avatcado from "@avatcado/node";

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

console.log(data?.meta.mode); // "test"
console.log(data?.data.company.name); // "Test GmbH"

from avatcado import Avatcado

avatcado = Avatcado("avat_test_your_api_key")
result = avatcado.vat.validate("DE111111111")

print(result.meta.mode)  # "test"
print(result.data.company.name)  # "Test GmbH"

​

Valid response

{
  "data": {
    "valid": true,
    "vat_number": "DE111111111",
    "country_code": "DE",
    "company": {
      "name": "Test GmbH",
      "address": "Berlin, Germany"
    },
    "requested_at": "2026-03-07T12:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "request_duration_ms": 2,
    "mode": "test"
  }
}

​

Error response

{
  "error": {
    "code": "upstream_unavailable",
    "message": "Upstream service returned an error",
    "docs_url": "https://docs.avatcado.com/errors/upstream_unavailable"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440001",
    "request_duration_ms": 1
  }
}

​

Behavior notes

• Consultation numbers are included for all tiers when a matching requester_vat_number is provided
• Input normalization works the same as live mode. "de 111.111.111" becomes DE111111111
• Non-magic numbers return a generic valid result, so any integration test with valid-format VAT numbers will succeed