Saltar al contenido
Address Validation iO

Esta documentación solo está disponible en inglés.

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:

JSON
{ "error": "invalid_api_key" }

Some 400 errors add fields, the names of the invalid fields or query parameters:

JSON
{ "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:

text
x-avio-request-id: 93186fb4-50ed-4824-8abd-05a3dfb4806a

Log 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/validate answers 200 with decision: "skipped".
  • An order re-check answers 200 with decision: "skipped".
  • POST /v1/emails/validate and POST /v1/phones/validate answer 200 with result: "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.