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 successful lookup spends one credit (see below).

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. Each successful lookup (200 response) spends one credit; failed requests (4xx and 5xx) do not. The native, getAddress.io, and Loqate endpoints all spend one credit per call. GET /plan is read-only and never spends a credit.

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 and credit usage.

"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.