Skip to main content

​
tier_insufficient

HTTP Status: 403 Forbidden

​
Example response

{
  "error": {
    "code": "tier_insufficient",
    "message": "Batch validation requires a Pro or Business plan",
    "docs_url": "https://docs.vatly.dev/errors/tier_insufficient"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

​
What happened?

You tried to use a feature that is not available on your current tier. This happens when:
  • Calling the batch validation endpoint on the Free tier (requires Pro or Business)

​
How to fix

  1. Upgrade your plan: Visit the Vatly dashboard to upgrade to Pro or Business. The upgrade takes effect immediately.
  2. Use single validation instead: If you only need to validate a few VAT numbers and don’t want to upgrade, use the single GET /v1/validate endpoint which is available on all tiers.
TierBatch Validation
FreeNot available
ProUp to 50 per request
BusinessUp to 50 per request

​
Common mistakes

  • Assuming all endpoints are available on Free: Some features like batch validation are reserved for paid tiers
  • Using a test key and expecting different behavior: Tier restrictions apply to both live and test keys. A test key on a Free account still returns tier_insufficient for batch requests
  • unauthorized - API key is invalid or missing (different from tier restrictions)
  • rate_limit_exceeded - Monthly quota exhausted (different from tier gating)