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. | Wait until the person has typed 3 characters before calling. 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. Autocomplete keeps working; only charged calls are refused. |
| 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. |
| 402 | feature_unavailable | The endpoint is not included in the workspace’s plan. | Check the plan in the console under Billing. |
| 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. 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 instead; 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 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. |
Not errors: notices
A notice rides on a successful 200 response to explain why it is empty. Today there is one: 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.
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