API
Errors and rate limits
The platform API's error format, request ids, body size limit, hourly limits and which requests are safe to retry.
This page explains what the Address Validation iO platform API returns when a request fails, how the hourly limits work and how to retry safely.
Error format
A failed request returns a non-2xx status and a JSON body with an error code:
{ "error": "invalid_api_key" }Some 400 errors add fields, the names of the invalid fields or query parameters:
{ "error": "invalid_query", "fields": ["count"] }Branch on the error code, not on the status alone. Handle a code you don't know like a generic failure.
Request id
Every response, successful or not, carries an x-avio-request-id header:
x-avio-request-id: 93186fb4-50ed-4824-8abd-05a3dfb4806aLog it with every failed request. When you contact support, quote the request id so we can find the request. The id is only sent as a header, not in the response body.
Error codes
These are the codes the endpoints in these guides can return:
| Status | error |
When |
|---|---|---|
| 400 | invalid_body |
The body isn't valid JSON or doesn't match the endpoint's schema (for example countryCode is missing). |
| 400 | invalid_order_id |
The order id in the path doesn't match ^[A-Za-z0-9._:-]{1,64}$. |
| 400 | invalid_period |
GET /v1/usage got a period that isn't yyyy-mm. |
| 400 | invalid_query |
A bad query parameter, such as count on GET /v1/usage/months. Comes with fields. |
| 400 | provider_override_not_allowed |
A validate request sent provider, but your shop isn't allowed to choose its provider. |
| 401 | missing_api_key |
No Authorization header. |
| 401 | invalid_api_key |
The key is malformed, unknown or revoked. |
| 403 | tenant_suspended |
API access for your shop is suspended. |
| 403 | not_available |
The endpoint exists, but isn't available to your shop or key. |
| 404 | order_not_found |
No stored order with this id. |
| 404 | not_found |
No endpoint at this path. |
| 405 | method_not_allowed |
The path exists, but not with this HTTP method. |
| 409 | order_conflict |
The order changed while your request ran. See Retries. |
| 409 | correction_locked |
A customer correction arrived after your shop's correction time limit. |
| 413 | body_too_large |
The request body is larger than 16 KB. |
| 429 | rate_limited |
An hourly limit is used up. See Rate limits. |
| 500 | internal_error |
Something failed on our side. Safe to retry for GET, PUT and DELETE. |
The configuration endpoints for platform integrations have a few more codes (such as settings_conflict and route_conflict). They are listed in the API reference.
Body size limit
Request bodies can be at most 16 KB (16,384 bytes). A larger body is rejected with 413 body_too_large before the key is even checked. A normal address, order or correction is far below this limit, so a 413 usually means you are sending fields the API doesn't use.
Ignore unknown fields
/v1 only ever adds fields to responses. Never fail on a field you don't know, and don't rely on the order of keys.
Rate limits
Limits are counted per shop and per hour. Each hour starts at the full limit at the top of the hour (UTC). The default limits are:
| What is counted | Limit per hour |
|---|---|
Address checks with POST /v1/addresses/validate that ask a provider (cached answers are not counted) |
2,000 |
Address checks with context: "test" |
100 |
| Email checks (standalone and inside orders) | 200 |
| Phone checks (standalone and inside orders) | 200 |
Order re-checks (a known order with a new address or force) |
500 |
| Order corrections | 500 |
Reads of logs, stats and GET /v1/usage/months |
1,000 |
A new order has no hourly limit. If your volume needs higher limits, contact us.
What happens at the limit
The checks that run during checkout fail open, so a used-up limit never blocks your checkout:
POST /v1/addresses/validateanswers200withdecision: "skipped".- An order re-check answers
200withdecision: "skipped". POST /v1/emails/validateandPOST /v1/phones/validateanswer200withresult: "unknown".- Inside an order, an email or phone check that hit the limit is left out of the order result.
Only these requests answer 429 rate_limited: address checks with context: "test", order corrections, and the log, stats and usage-months reads. There is no Retry-After header. Wait for the next UTC hour, or slow down.
Retries
Retry only when it's safe:
| Failure | Retry? |
|---|---|
Network error, timeout, 5xx on GET, PUT or DELETE |
Yes, once or with backoff. These requests are idempotent. |
Network error, timeout, 5xx on POST |
Not automatically. A POST may already have run a check, and email and phone checks are charged per check. |
400, 401, 403, 404, 405, 413 |
No. Fix the request or the key first. |
409 order_conflict |
Yes, after you reload the order on your side and send it as it is now. |
429 rate_limited |
Only after the hour resets. |
PUT /v1/orders/{orderId} is idempotent: sending the same order with the same shipping address again returns the stored result without a new check and without being metered again. That makes it safe to retry after a timeout, even if the first request did reach AVIO. See Orders.
A 409 order_conflict means another request saved a different address or result for the same order while yours ran, or the order was erased. AVIO doesn't guess which version is current: send the order again as it is now in your system.
The official clients follow the same rules: they retry GET, PUT and DELETE once on a network error, a timeout or a 5xx, and never retry POST. They use a 5-second timeout per attempt.
Fail open at checkout
When AVIO can't be reached, times out or answers 5xx during checkout, let the customer continue. Treat the result like decision: "skipped" and, if you submit orders, check the order later with PUT /v1/orders/{orderId}.
Full reference
Every operation, with the error codes it can return, is in the API reference.