API error codes
Every error from the address endpoints is JSON with the same shape. The code is stable and safe to switch on. The message is for a human and may change. The docs field links to the row below for that code.
"error": {
"code": "invalid_key",
"message": "Invalid or revoked API key.",
"docs": "https://wattleaddr.com.au/docs/errors#invalid_key"
}
}
All codes
| Status | code | What happened | What to do |
|---|---|---|---|
| 400 | bad_request | The query (q) or address is under 3 characters, or over the length limit. For suburb and postcode search the minimum is 2 characters, and session is required. Suburb verify needs at least two of suburb, state and postcode. | Wait until the person has typed 3 characters before calling address search, or 2 for suburb and postcode search. Trim very long input. |
| 401 | unauthorized | No API key was sent. | Add an Authorization: Bearer YOUR_KEY header (secret key), or ?key= for a publishable key in the browser. |
| 401 | invalid_key | The key is wrong, has been revoked, or has a typo. | Copy it again from the console, or create a new key. Revoked keys never come back. |
| 402 | quota_exceeded | This month’s lookups are used up and your plan does not run over (Free, Shopify, a cancelled plan, or a paid plan with a spending cap set at your request), or a paid plan has reached the overage ceiling of five times its included lookups. The message says which. | Upgrade in the console under Billing, or wait for the period to roll over. If the message says the overage ceiling was reached, contact support to lift it; a plan change only takes effect next period. Address autocomplete keeps working. Suburb and postcode autocomplete is refused too, because it can be charged. |
| 402 | test_mode_expired | A test key was used after the free test period (15 days from account creation). | Create a Live key in the console. Live keys work on every plan, including Free. The one exception is the suburb and postcode API, which needs a paid plan on a live key. |
| 402 | feature_unavailable | The endpoint is not included in the workspace’s plan. Today that means a live key on the Free plan calling the suburb and postcode API. Nothing was charged. | Upgrade to Starter or above in the console under Billing. Until then, fall back to a free-text suburb field. Test keys can use the suburb and postcode API during your account’s first 15 days. |
| 403 | forbidden_referrer | A publishable key was used from a domain that is not on its allowed list. | Edit the key in the console and add the domain to Allowed domains. Match the exact host the page is served from. |
| 403 | forbidden_key_type | A publishable (browser) key was used to call verify (address or suburb). Publishable keys can only call autocomplete and retrieve. | Call verify from your server with a secret key. If a person is typing the address, use autocomplete and retrieve with the publishable key. Verify is for addresses you already hold. |
| 403 | forbidden_ip | A secret key was used from an IP address that is not on its allowed list. | Edit the key in the console and add the address to Allowed IPs / CIDRs, or clear the list to allow any IP. |
| 404 | not_found | No address, suburb or postcode pair has that id. | Use an id exactly as it came back from an autocomplete suggestion. Ids can change between G-NAF releases, so re-search rather than replaying an old one. |
| 429 | rate_limited | Too many requests per second on one key. | Wait the number of seconds in the Retry-After header, then retry. Debounce keystrokes in the browser. |
| 503 | engine_unavailable | The suburb and postcode data is not loaded on this server. Nothing was charged. | Wait a few seconds and retry. If it keeps happening, check wattleaddr.com.au/status. |
Not errors: notices
A notice rides on a successful 200 response to explain an empty or substituted result. There are three. The first: a query for a PO Box, GPO Box, Locked Bag or Private Bag returns an empty suggestions array and a notice with code: "postal_address_unsupported", because G-NAF holds physical addresses only. Show notice.message and offer a separate postal field. verify returns the same notice with matched: false and billed: false. Neither is charged. The second, street_number_not_found, comes from autocomplete only: the street and suburb matched but there is no exact match for the number in the area searched, so the suggestions are the nearest street numbers. The third, unit_not_found, also comes from autocomplete only: the building matched in your suburb but there is no exact match for the unit, shop, suite or level you typed, so the building leads the list. Show the list rather than taking the first one in either case.
Quota headers
Every successful response, and a 402 quota_exceeded, carries X-WattleAddr-Quota-Limit and X-WattleAddr-Quota-Remaining on plans that have a quota. A 429 carries Retry-After in seconds.
Back to the quickstart, or try each call live in the interactive reference. Questions? support@wattleaddr.com.au