Rate Limits & Errors

HTTP status codes

The API uses standard HTTP status codes to indicate success or failure:

Error response format

Native (/v1) and Loqate responses return a machine-readable error code and a human-readable message:

{
  "error": "invalid_postcode",
  "message": "Invalid postcode format"
}

Validation failures (400) may also include a details array. The getAddress.io-compatible endpoints instead return a single Message field, matching getAddress.io's format.

Request limits

There is no fixed requests-per-second cap. In practice your throughput is bounded by your credit balance — each completed lookup spends one credit (see below). Type-ahead suggestion requests are free, but still require a balance above zero.

If the search backend is briefly unavailable you may receive a 503. This is transient — retry after a short delay with exponential backoff.

Credit usage

SnapAddress is billed as one-off credit packs, not a monthly subscription. One credit is spent per completed lookup.

A lookup is one completed address search: a full postcode lookup, or an address selected from autocomplete. Searching as the customer types is free, so one completed address search uses exactly one lookup.

GET /plan is read-only: it never spends a credit and works at a zero balance.

The free endpoints are not unmetered — they are part of an address capture flow that ends in a lookup. They still need credits on the account, so at a zero balance suggestions stop too (429 on the native and getAddress.io endpoints, 402 on Loqate).

A lookup that finds nothing still counts. A charged endpoint returning 404 — a valid query with no matching address — spends a credit. Royal Mail's Transaction definition covers the verification of a query, not just the data it returns.

Requests rejected before the search runs never spend a credit: malformed queries (400), missing or revoked keys (401), and requests refused for an empty balance (429 / 402). A credit is taken before the search executes, so in the rare case where the backend then fails (503 / 500) it will already have been spent — contact us and we will put it right.

GET /v1/postcodes/{postcode} returns up to 100 addresses per request. Postcodes holding more than 100 addresses are paged with the page parameter, and each page is a separate lookup.

Credits are spent oldest-first — the soonest-to-expire pack is used before newer ones. Check your remaining balance on the dashboard or via the API (GET /plan).

Credit packs are valid for 12 months from purchase; the free trial credits are valid for 3 months. Unused credits expire at the end of that period — a Royal Mail PAF licensing requirement that every licensed provider works under. Topping up does not extend the validity of credits you already hold.

Prices are current at the time of writing — see the pricing page for the latest.

Running out of credits

When your balance reaches zero, lookups are rejected — not silently billed or queued:

• Native (/v1/...) and getAddress.io-compatible endpoints return 429.
• Loqate-compatible endpoints return 402 (matching Loqate's behaviour).

Buy another credit pack from the pricing page to resume. The WooCommerce plugin falls back to manual address entry when credits run out, so checkout keeps taking orders.

Common issues

"Invalid postcode format" (400)

The postcode contains characters that are not valid in a UK postcode. Ensure you are passing only the postcode, without additional text or special characters.

Query too short (400)

The autocomplete endpoint requires at least 2 characters. Single-character queries return a 400 error. Check q.length >= 2 client-side before calling the API to avoid unnecessary errors. Autocomplete is free, so this costs you nothing either way — it just saves a round-trip.

"Unauthorised" (401)

• Check that your API key is correct and has not been revoked
• On the native /v1 endpoints, pass the key as the x-api-key header. The getAddress.io and Loqate compatibility endpoints take the key as a query parameter (api-key or Key) instead.
• Confirm that your account is active

"Postcode not found" (404)

The postcode is syntactically valid but does not exist in the Royal Mail PAF database. This can happen with:

• Newly created postcodes that have not yet been added to PAF
• Postcodes that have been terminated
• Typos that happen to match valid postcode formatting

"No credits" (429 or 402)

Your credit balance is exhausted. Native and getAddress.io endpoints return 429; Loqate endpoints return 402. Buy another credit pack from the pricing page to resume.

Timeouts

If requests are timing out, check:

1. Your server can reach api.snapaddress.io over HTTPS (port 443)
2. No firewall or proxy is blocking the connection

A 503 response means the search backend is briefly unavailable — retry after a short delay.

If the issue persists, check the status page or contact support.