# Error Codes and Common Fixes AddressZen API error codes with causes and fixes, ordered by how often each one comes up in support. Every error response is JSON with a numeric `code` and a `message`. The HTTP status gives the class of error and the body `code` gives the cause. A successful request returns HTTP 200 with code `2000`. ```json { "code": 4010, "message": "Invalid Key" } ``` ## 4010 - Invalid Key **Message:** `Invalid Key` **HTTP Status:** 401 The API did not recognize your API key. The key is missing, mistyped or has been deleted. ### Potential Fixes 1. **Check for typos.** Copy the key from [your AddressZen account](https://account.addresszen.com/tokens). 2. **Check the query string parameter name.** Pass the key as `api_key`, not `api-key`. 3. **Check the Authorization header format.** The header is `Authorization: api_key="ak_yourkey"`, with the key in double quotes. ## 4011 - URL Not on Allowed List **Message:** `Requesting URL not on whitelist` **HTTP Status:** 401 The request's `Referer` or `Origin` header did not match any URL on your key's [allowed URL list](/docs/guides/allowed-urls.md). The same code with the message `Forbidden` means the key has an IP allow list and the request came from an IP that is not on it. ### Potential Fixes 1. **Check if you need Allowed URLs.** Server side requests carry no `Referer` or `Origin` header, so nothing can match. Remove the allowed URLs if the key stays private, or use a separate key for server side calls. 2. **Review your Allowed URL configuration.** Each entry must match the scheme and host exactly, for example `https://example.com` with no trailing slash or path. The [API key security guide](/docs/guides/api-key-secure.md) covers the rules. 3. **For `Forbidden`, check the IP allow list.** Add the caller's IP in your key settings or remove the IP restriction. ## 4020 - Balance Depleted **Message:** `Key balance depleted` **HTTP Status:** 402 Your API key has no lookups left. ### Potential Fixes 1. **Top up your balance.** [Buy more lookups](/docs/guides/purchasing-lookups.md) from [your AddressZen account](https://account.addresszen.com/tokens). 2. **Enable automated top-ups.** Stop this recurring by [enabling automated top-ups](/docs/guides/automated-topups.md). ## 4021 - Lookup Limit Reached **Message:** `Lookup Limit Reached` **HTTP Status:** 402 Your API key has a daily, monthly or per IP limit configured and the request would exceed it. Licensee daily limits return the same code. ### Potential Fixes 1. **Remove the limit.** Delete the responsible limit in your [key settings](/docs/guides/api-key-settings.md) for an immediate fix. 2. **Raise the limit.** Adjust the daily, monthly or IP limit in your key settings. ## 4015 - Inadequate License **Message:** `Inadequate licence to access data` **HTTP Status:** 401 Your API key is not enabled for the product you requested. Email validation, phone number validation and address verification are each enabled per key. ### Potential Fixes 1. **Enable the product on your key.** Check the key in [your AddressZen account](https://account.addresszen.com/tokens). 2. **Contact support.** If the product is not available on your plan, email . ## 4000 - Invalid Syntax **Message:** `Invalid syntax submitted` or a validation message naming the field **HTTP Status:** 400 The API could not parse the request. Common causes are a JSON body that does not parse, a URL with malformed percent encoding, or a request to `/verify/addresses`, `/emails` or `/phone_numbers` that fails schema validation. Validation failures include an `errors` array with a `path` and `message` for each invalid field. ### Potential Fixes 1. **Send valid JSON.** Encode the body as UTF-8 and set `Content-Type: application/json`. 2. **Fix each field in `errors`.** The `path` names the field and the `message` says what is wrong with it. 3. **Percent encode query values.** Encode spaces, `#`, `&` and non ASCII characters before they go in the URL. ## 4048 - Address Not Found **Message:** `Address not found` **HTTP Status:** 404 The id passed to `/autocomplete/addresses/{id}/usa` or `/places/{id}` did not resolve. Ids expire and differ between datasets. Do not build them by hand. ### Potential Fixes 1. **Take ids from a search response.** Resolve an id only after receiving it from a preceding autocomplete or places search. 2. **Resolve promptly.** Do not store ids for later use. ## 4150 - Unsupported Media Type **Message:** `Unsupported Media Type` or `Unsupported Character Set received` **HTTP Status:** 415 A POST request arrived without a JSON content type, or with a character set other than UTF-8. ### Potential Fixes 1. **Set the content type.** Send `Content-Type: application/json` on every POST, including `POST /verify/addresses`. 2. **Use UTF-8.** If you set a charset, it must be `utf-8`: `Content-Type: application/json; charset=utf-8`. ## 4290 - Request Timed Out **Message:** `Request timed out. Please wait and try again later` **HTTP Status:** 429 An address verification or phone number validation request exceeded the time limit of about 10 seconds. ### Potential Fixes 1. **Retry with backoff.** Wait a few seconds, then resend the request. 2. **Simplify the query.** Long or unusual inputs take longer to process. 3. **Contact support if it persists.** Email with the request and a timestamp. ## 5001 - Uncatalogued Error **Message:** `Uncatalogued Error` **HTTP Status:** 500 Something failed on our side that the API could not classify. ### Potential Fixes 1. **Retry once.** Most uncatalogued errors are transient. 2. **Report it.** If it repeats, email with the full request (minus your key), the response body and the timestamp. ## Other Codes Less common codes, grouped by HTTP status. | Code | HTTP Status | Message | Where | Fix | | ------- | ----------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `404` | 404 | `404 Page not found` | Any unknown path | Check the path and the `/v1/` prefix | | `4001` | 400 | `Validation failed on your submitted data` | Key, config and licensee writes, including an invalid `rate_limit` in key settings | Check each field against the endpoint reference | | `4005` | 400 | `Invalid end date` | [Key usage](/docs/api/key-usage.md) and [key logs](/docs/api/key-logs.md) | Send `end` as an ISO 8601 date | | `4006` | 400 | `Invalid start date` | Key usage and key logs | Send `start` as an ISO 8601 date | | `4007` | 400 | `Invalid Date Range: start date is after end date` | Key usage and key logs | Correct the dates | | `4008` | 400 | `Invalid Date Range: range specified needs to be 90 days or less` | Key usage and key logs | Query in windows of 90 days or fewer | | `4009` | 400 | `Too Many Tags Queried: please specify no more than 3 tags to query` | Key usage and key logs | Filter by at most 3 tags per query | | `40010` | 400 | `Invalid source IP address provided` | Keys with a per IP limit receiving a malformed source IP header | Send a valid IPv4 or IPv6 address or drop the header | | `40011` | 400 | `Invalid search query received` | [Email validation](/docs/api/email-validation.md) and [phone number validation](/docs/api/phone-number-validation.md) without a string `query` | Send a single `query` string | | `40016` | 400 | `Invalid search query provided. Please review your inputs` | Autocomplete and places search with unparsable filter or bias parameters | Check parameter names and formats against the endpoint reference | | `40017` | 400 | `Invalid email query string. Email string length is too long. Max length 320` | Email validation | Trim the query to 320 characters | | `40018` | 400 | `Invalid query. The q or query parameter is required` | [Address verification](/docs/api/address-verify.md) without `query` | Include `query` in the JSON body | | `4012` | 401 | `Forbidden` | Key management routes with credentials for a different account | Use the user token that owns the key | | `4013` | 401 | `A Sub Licensee Key is required to perform this action` | Keys configured for [sublicensing](/docs/guides/sublicensing.md) used without a `licensee` | Pass `licensee` or use the licensee key | | `4014` | 401 | `Invalid API Key provided for licensee` | The `licensee` belongs to a different key | Pair the licensee with its parent key | | `4016` | 401 | `You have requested an invalid context` | Address verification with an unsupported `context` | Omit `context` or send a supported value | | `4041` | 404 | `User not found` | Key management routes with an unknown user token | Check the user token | | `4042` | 404 | `Key not found` | `/keys/{key}` and its child routes with an unknown key | Check the key in the path | | `4045` | 404 | `No licensee found` | `/keys/{key}/licensees/{licensee}` | Check the licensee id | | `4047` | 404 | `Config not found` | `/keys/{key}/configs/{config}` | Check the config id | | `4090` | 409 | `Unable to perform transaction due to duplicate keys` | Creating a config or licensee that duplicates a unique field | Change the conflicting value or update the existing record | | `4291` | 429 | `Too many requests. Please contact support` | Keys under two days old flagged as high risk | Email | | `5002` | 500 | `Search request reached internal timeout limits` | Search backend timeout | Retry. Shorten the query | ## 503 - Rate Limited **HTTP Status:** 503 The API limits each IP address to 30 requests per second. Requests over the limit receive HTTP 503 with no body code. ### Potential Fixes 1. **Back off and retry.** Spread requests across time or add a short delay between them. 2. **Ask for a higher limit.** If you need more than 30 requests per second from one address, email .