Documentation Index

Fetch the complete documentation index at: https://docs.vatly.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

tier_insufficient

​

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?

• 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.

​

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

​

Catching this error with the SDKs

import Vatly, { AuthenticationError } from '@vatly/node';

const vatly = new Vatly('vtly_live_your_api_key');
const { data, error } = await vatly.vat.validate({ vatNumber: '...' });

if (error instanceof AuthenticationError) {
  console.log(error.message);
}

​

Related errors

• unauthorized - API key is invalid or missing (different from tier restrictions)
• rate_limit_exceeded - Monthly quota exhausted (different from tier gating)