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.

{
  "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.
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.

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 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 from your AddressZen account.
2. Enable automated top-ups. Stop this recurring by enabling automated top-ups.

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 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.
2. Contact support. If the product is not available on your plan, email support@addresszen.com.

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 support@addresszen.com 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 support@addresszen.com 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 and key logs	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 and phone number validation 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 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 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 support@addresszen.com
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 support@addresszen.com.