Test Mode

Test your integration without hitting real upstream services or consuming quota

Test Mode

Test mode lets you build and test your Vatly integration without making real VIES/HMRC calls or consuming your monthly quota. Use a vtly_test_ API key instead of a vtly_live_ key.

How it works

• No upstream calls — Requests never reach VIES or HMRC
• No quota usage — Test requests don’t count toward your monthly limit
• No rate limit headers — Since there’s no quota, rate limit headers are omitted
• 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

Use these specific VAT numbers to trigger predictable scenarios:

VAT Number	Scenario	Status	Company
DE111111111	Valid EU company	200	Test GmbH, Musterstrasse 1, Berlin
GB111111111	Valid UK company	200	Test Ltd, 1 Test Street, London
FR11111111111	Valid French company	200	Test SARL, 1 Rue de Test, Paris
DE222222222	Valid, no address	200	Test GmbH, address null
DE000000000	Invalid VAT	200	valid: false, no company
DE999999999	Upstream error	503	upstream_error
DE888888888	Service unavailable	503	upstream_unavailable
DE777777777	Rate limit exceeded	429	rate_limit_exceeded

Any other properly formatted VAT number returns valid: true with a generic “Test Company” / “Test Address”.

Examples

curl

curl -H "Authorization: Bearer vtly_test_your_api_key" \
  "https://api.vatly.dev/v1/validate?vat_number=DE111111111"

Valid response

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

Error response

{
  "error": {
    "code": "upstream_error",
    "message": "The upstream VAT validation service returned an error",
    "docs_url": "https://docs.vatly.dev/errors/upstream_error"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440001",
    "mode": "test"
  }
}

Behavior notes

• Consultation numbers are included for Business and Scale tiers, stripped for Free tier (same as live mode)
• 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