Skip to main content

​
Test Mode

Test mode lets you build and test your Vatly integration without making real VIES/HMRC/BFS/Bronnysund 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, 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 vtly_test_ keys. Use a vtly_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

Use these specific VAT numbers to trigger predictable scenarios:
VAT NumberScenarioStatusCompany
DE111111111Valid EU company200Test GmbH, Berlin, Germany
GB111111111Valid UK company200Test Ltd, London, United Kingdom
FR11111111111Valid French company200Test SARL, Paris, France
DE222222222Valid, no company details200valid: true, company null
DE000000000Invalid VAT200valid: false, company null
DE999999999Upstream error503upstream_unavailable
DE888888888Service unavailable503upstream_unavailable
DE777777777Rate limit exceeded429rate_limit_exceeded
DE666666666Burst limit exceeded429burst_limit_exceeded
DE555555555Stale cache fallback200Test GmbH (stale), source_status: "unavailable"
CH111111118Valid Swiss company200Test AG, Zurich, Switzerland
CH222222225Valid Swiss UID, not VAT-registered200valid: false, company present
LI111111118Valid Liechtenstein company200Test Anstalt, Vaduz, Liechtenstein
NO123456785Valid Norwegian company, MVA-registered200Test AS, Oslo, Norway
NO987654325Valid Norwegian org, not MVA-registered200valid: false, company present
CH999999996BFS upstream error503upstream_unavailable
NO999999999Bronnysund upstream error503upstream_unavailable
Any other properly formatted VAT number returns valid: true with a generic “Test Company” / “Test Address”.

​
Examples

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": "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.vatly.dev/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