Error reference
Complete list of error codes, HTTP status codes, and links to detailed guides for each.
Every error response follows this envelope:
{
"error": {
"code": "unauthorized",
"message": "Missing API key."
},
"meta": {
"request_id": "a1b2c3d4-...",
"latency_ms": 0
}
}Error codes
| Code | HTTP | When | Guide |
|---|---|---|---|
unauthorized | 401 | Missing / invalid / revoked API key | → |
plan_required | 402 | Endpoint requires a higher plan | → |
invalid_format | 400 | Malformed body or missing required fields | → |
country_unsupported | 400 | Country not in the 32 supported | → |
country_unknown | 404 | Country code not in the rates dataset | → |
batch_too_large | 400 | More than 50 items in a batch request | → |
webhook_limit_reached | 400 | More than 5 webhook endpoints registered for this key | → |
seller_country_unsupported | 400 | /decide: seller not in EU-27 | → |
b2c_not_supported | 400 | /decide: B2C transactions not supported | → |
buyer_vat_not_registered | 400 | /decide: buyer VAT invalid or unregistered | → |
not_found | 404 | Audit record or resource not found | → |
rate_limited | 429 | Monthly quota exceeded | → |
registry_unavailable | 502 | Upstream registry down or faulted | → |
Retry guidance
- 429: respect the
Retry-Afterheader. Don't busy-retry. - 502: exponential backoff: 250ms → 500ms → 1s, max 3 retries.
- 400 / 401 / 402 / 404: do not retry. Fix the request or key.