Errors

Every error is a problem details body (application/problem+json, RFC 9457). Where a body has a code, branch on it, never on the wording. A problem's type links to its entry on this page.

{
    "type": "https://getaddress.io/docs/errors#unauthorized",
    "title": "Unauthorized",
    "status": 401,
    "detail": "The api-key query string parameter is missing or invalid.",
    "code": "unauthorized"
}

unauthorized — 401

No api-key, a key or domain token we don't know, or an API key sent from a web page. Check the key in your account; from a browser, use a domain token.

forbidden — 403

The key is genuine but may not do this: the admin key used for an address look-up, or an API key used for /usage, PUT /subscription/label or PUT /subscription/auto-upgrade. Use the other key of the same subscription.

An address look-up on a subscription that has ended is refused with 403 too, and so is one on a free trial once its 30 days are up: the detail then says the trial has ended. Choosing a plan in your account switches the same keys back on straight away.

domain-token-scope — 403

A domain token was used for something other than an address, location, typeahead or company look-up, such as /usage. Call it from your server with the right key.

domain-token-rate-limit — 429

The domain token's per-visitor or token-wide limit was reached. Wait the number of seconds in Retry-After.

Rate limit — 429

Your plan's requests per 5 minutes are used up, or one key sent too many requests in a minute. Wait the number of seconds in Retry-After.

Daily limit, monthly buffer — 429

Your plan's look-ups for today are used up, and any monthly buffer with them. Metered endpoints refuse until midnight UTC (Retry-After says how long); free endpoints keep answering. See Usage.

Bad request — 400

A parameter or body is missing or malformed. The title names the field; the detail says what is wrong.

Not found — 404

No address, place, business or batch with that id. A 404 costs nothing.

Service unavailable — 503

The address data or the key store was briefly out of reach. Retry shortly.