Skip to main content

Error codes

The API may return "success": false if there was an issue with your request. This could be because the request was not formatted correctly or because the configuration in the Portal is incomplete.

Example API error response
{
  "completions": [],
  "message": "Key not found",
  "error_code": "1001",
  "success": false
}

Below is a list of possible error codes, along with additional information about how to resolve them.

1000 Validation error

Returned when one of the supplied parameters is missing or incorrect. The response will contain a message attribute which explains the cause of the validation error. An example JSON response is shown below for a request which failed to include the q parameter:

{
  "completions": [],
  "message": "Q can not be blank",
  "error_code": "1000"
}

Resolution: Check that the supplied parameters contain valid values, and that the mandatory parameters have been included.

1001 Key not found

Returned when the key included in your API call cannot be found in our database.

Resolution: Compare the key included in your API call with the key listed in the credentials section in the Portal.
Also confirm there are no additional spaces or characters in your API call.

1002 Key not provided

Returned when you fail to send through your key with each request. The key is a mandatory parameter.

Resolution: Check that you are using the correct parameter name key.

1003 Domain not registered with Addressfinder

The URL of the website where you are using the Addressfinder widget is not listed correctly in the allowed domains in the Portal.

Here are a few ways this could have happened:

  • The domain was not added in the Portal (e.g. domain listed: some-other-site.com, URL: example.com).
  • The domain in the Portal is listed with www but the website URL doesn't contain www (e.g. domain listed: www.example.com, URL: example.com).
  • The website domain is added, but it has the wrong subdomain (e.g. domain listed: staging.example.com, URL: form.my-site.com).

Resolution: Log in to your account and add the domain of your website to your account.

Adding the root domain, which means the domain without any prefix, will allow queries from all subdomains. For example, if you would like to use the widget on staging.example.com and example.com, all you need to do is add example.com in the Portal.

1004 Secret not provided

Returned when you fail to send through your secret with an API call.

Can also occur when using the widget and the HTTP Referer header is not included.

Resolution: Include the secret in your API call. You can find it in the credentials section in the Portal.

When using the widget, you must load the page from a web server (e.g. localhost) and not a file:// scheme.

1005 Direct API calls are not permitted on your current plan

Returned if you try to call the API and you are on a plan that doesn't offer direct API access.

Resolution: Go to your account and upgrade to a plan with direct API access.

1006 Invalid credentials

Returned when the supplied key and/or secret value are incorrect.

Resolution: Compare the key included in your API call with the key listed in the credentials section in the Portal.

Also confirm there are no additional spaces or characters in your API call.

1008 Secret should not be supplied

This is a safety check to ensure that the secret parameter has not been included when making requests from your web browser. You should never include the secret on any web page.

Resolution: The secret should be used for server-to-server API calls only.

Check that you are not sending the Referer or Origin headers when making direct API calls.

1009 The address autocomplete feature is unavailable as it has exceeded the number of free lookups. Please contact the website owner.

Returned when your account hits the usage limit for the current billing period. This only applies to organisations on the legacy free plans.

Resolution: Go to your account and upgrade to a paid plan.

1011 The record you are trying to load does not exist

Returned when the supplied address identifier cannot be found. This can happen when a stale identifier is included in the API call.

Resolution: Do not save address identifiers in your database, as they are transient and may change after each database update.

1015 Domain parameter must not be included in a web request

You have included a domain parameter in your browser based API call. The domain parameter is for direct API calls only.

Resolution: Remove the domain parameter from your web request.

1016 This domain has been blocked

These credentials are not permitted to be used on this domain.

Resolution: Contact our support team at support@addressfinder.com to discuss removing the block.

1017 This service is not enabled on your current plan

You have attempted to use an Addressfinder service that is not available on your current plan.

Resolution: Go to your account and upgrade to a different plan.

1018 Your IP address has been blocked for these credentials

This service has been configured to only allow access from defined IP addresses.

Resolution: Go to your account and add your IP address to the allow list.

1019 HTTP Referer or Origin header record must be present when making a browser initiated request

You have attempted to use the Addressfinder widget from a browser that does not include the referrer or origin headers along with each request.

Resolution: Confirm that this request was sent from a valid web server (not the local filesystem), and that you do not have browser plugins interfering with the request.

1020 Your Addressfinder trial has ended

Returned when the trial term has ended.

Resolution: Log in to your account and upgrade to a paid plan.

1021 Your Addressfinder trial has exceeded its allowed lookups

Returned when you have exceeded the number of lookups permitted on the trial plan.

Resolution: Log in to your account and upgrade to a paid plan.

1022 Postal addresses are not enabled on your current plan

You have attempted to query postal addresses, this service is not included in your current plan.

Resolution: You can use our service without specifying postal addresses.

  • For Australia, use the param gnaf:1 (and remove au_paf:1).
  • For New Zealand, remove delivered:1 and post_box:1.

If you would like to use postal addresses, log in to your account and upgrade to a paid plan.

1023 Your Addressfinder plan is paused

This error is returned when you attempt to use Addressfinder service but have paused your Addressfinder plan.

Resolution: Log in to your account and switch to a paid plan.