Errors & rate limits
Postio uses the HTTP status code to convey the outcome class, and returns a stable machine-readable error code in the response body. Each key is limited to 30 requests per second.
Status codes
The HTTP status tells you the class of outcome:
| Status | Meaning |
|---|---|
| 200 | Success — including a "no match", which is still 200 with an empty results array. |
| 400 | Validation failed — a required parameter is missing or malformed. |
| 401 | Missing or invalid API key. |
| 402 | Out of credit — top up to resume billable requests. |
| 403 | Service disabled for this key, or the origin / IP is not allowed. |
| 429 | Rate limit exceeded — back off and retry. |
| 5xx | Server-side problem — safe to retry. |
A “no match” is not an error: a valid query with no result is a 200 with an empty results array, and it is not billed.
Error body
On any non-2xx, success is false, results is empty, and a top-level error field carries a stable code. details adds human-readable context, and meta.requestId is present on errors too:
{
"success": false,
"results": [],
"error": "invalid_api_key",
"details": "The x-api-key header is missing or not recognised.",
"meta": { "requestId": "dd273343-4597-4fa4-bcb6-c74a608c10dc" }
}Branch on the error code, not on the wording of details — the code is stable, the prose may be reworded. Log the requestId whenever you raise something with us.
Rate limiting
Each key is limited to 30 requests per second. Bursts past that return 429 — back off and retry. Sustained abuse can result in the key being suspended. If you legitimately expect higher throughput, get in touch and we will raise the limit.
Retrying safely
Every endpoint is a GET and therefore idempotent — a retry is always safe. Retry on 429 and 5xx with exponential backoff and jitter; do not retry a 400, 401, 402 or 403, which will fail identically until you fix the request. The official SDKs implement this policy for you (two retries, exponential backoff with full jitter).
FAQ
- What does HTTP 402 mean from the Postio API?
- A 402 means the API key is out of credit. Billable requests are paused until you top up the account balance; free endpoints (/connect and /address/search) keep working.
- Is a "no match" an error in the Postio API?
- No. A valid query that finds nothing — for example a real postcode with no delivery points — returns HTTP 200 with an empty results array, and it is not charged. Errors are reserved for genuine failures.
- What is the Postio API rate limit?
- Each API key is limited to 30 requests per second. Exceeding it returns HTTP 429; back off and retry. Higher limits are available on request via the contact page.