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.nz/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 or location look-up, typeahead or a postcode correction report, 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.

Postcode correction limit — 429

More than 100 postcode corrections today from one API key, or 20 from one visitor on a domain token. Try again the next day.

Postcode corrections paused — 403

A reviewer paused your account's postcode corrections: its reports were rejected and new ones are refused. Contact us if you think this is wrong.

Postcode unchanged — 409

The address already has the postcode you reported. Nothing to do.

Postcode review — 403

The postcode review routes are for our reviewers only, with a reviewer subscription's admin key. Any other account or key is refused.

Bad request — 400

A parameter or body is missing or malformed: for a postcode correction, a postcode that is not four digits or that no New Zealand address has, a source other than user or customer, or a note over 200 characters. The title names the field; the detail says what is wrong.

Not found — 404

No address, place 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.