rate_limited
Your monthly quota of live registry calls has been exhausted.
HTTP 429 · Too Many Requests
Example response
{
"error": {
"code": "rate_limited",
"message": "Monthly quota of 500 exceeded. Resets 2026-05-01T00:00:00Z."
},
"meta": {
"request_id": "a1b2c3d4-...",
"latency_ms": 0
}
}Headers on this response:
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746057600
Retry-After: 1382400What happened
Every plan has a monthly quota of live registry calls. Cache hits are free and don't count. When the quota is exhausted, all further requests that would require a registry call are rejected with 429 until the quota resets on the 1st of the next month.
How to fix
- Check
X-RateLimit-Remainingon every response to track remaining quota before hitting the limit. - Respect
Retry-After. It tells you the exact seconds until reset. Don't retry before then. - Use
cache=falsesparingly. Bypassing cache forces a live call and counts quota even if the same number was recently validated. - Upgrade your plan for a higher monthly quota.
- Cache validation results on your side (e.g. in your database) to avoid re-validating the same VAT numbers.
Common mistakes
- Busy-retrying on 429: retrying immediately wastes calls and won't succeed. Respect
Retry-After. - Not monitoring
X-RateLimit-Remaining: quota exhaustion mid-month is avoidable with monitoring. - Re-validating known customers on every checkout: store the validation result in your database with a timestamp. Re-validate only when the stored result is older than your compliance requirement (e.g. 30 days).
- Bypassing cache unnecessarily:
cache=falseis for audited compliance workflows, not default usage.
Related errors
plan_required: quota is fine but endpoint requires higher planbatch_too_large: request rejected before quota is consumed