​

tier_insufficient

​

Example response

{
  "error": {
    "code": "tier_insufficient",
    "message": "Batch validation requires a Pro or Business plan",
    "docs_url": "https://docs.avatcado.com/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)
• Submitting an async validation on the Free tier
• Configuring a webhook on the Free tier

​

How to fix

1. Upgrade your plan: Visit the Avatcado 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: Batch validation, async validation, webhooks and the national register fallback 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 Avatcado, { AuthenticationError } from '@avatcado/node';

const avatcado = new Avatcado('avat_live_your_api_key');
const { data, error } = await avatcado.vat.validate({ vatNumber: '...' });

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

from avatcado import Avatcado, AuthenticationError

avatcado = Avatcado("avat_live_your_api_key")

try:
    result = avatcado.vat.validate("...")
except AuthenticationError as e:
    print(e.message)

​

Related errors

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