Error handling

Refer to this page if you encounter an error while using the API.

Additional details about the error may be logged to your dashboard here.

Remember, you can always contact us if you have any questions.

HTTP status codes

The HTTP status code contained within each response shows whether your lookup was successfully performed.

You may wish to check for a status code of "200" to determine whether your lookup was successful.

The three other codes supported by the API are shown below.

HTTP status code Description
200 Lookup was successfully performed
403 Account-level error (e.g. Incorrect Search Key / API Key, no credit remaining)
404 Request URL was incorrect or malformed (e.g. Incorrect method name used)
500 Server-level error - please contact the Support team in this event

A status code other than "200" indicates there may be a configuration issue with your account, your request or the service itself. In this event, you may wish to use the free status method below to gather more information.

To find HTTP status codes you can put your request URL into a web browser with developer tools available and look under the Network tab. You can also detect the response code in most programming languages.

Service status updates

Should we have problems with any of our services they will be reported here -

Most common errors

When first getting started with the service, you may run into one or two common errors, depending on your usage. The most common errors and what to do about them are listed here.

Response Suggested fix
Browser Direct Lookups exceeded, retry later By default, your API key's security settings block too many lookups coming from a single unrecognised IP address. Increase your rate-limit for unlisted IP addresses, or consider whitelisting your server's IP address.
The Server IP Address is not registered When an API is not enabled for public access, every IP address that makes a request using it must be whitelisted. If you trust the displayed IP address, you can add it to your whitelist in your account's security settings.
Account doesn't have access to required datasets Your API key isn't currently enabled to access the dataset you are attempting to search. You can request access at this link.

Status endpoint

Returns system and account information which may be helpful for debugging problems in your scripts.

Lookup cost: 0 credits

Request structure[api-key]/status

Optional parameters

format xml | json (default unless header of application/xml is detected)

Response examples

Request: - View live response

    "correctsearchkey": true,
    "availablecredits": 0,
    "lookupservicesup": true,
    "state": "Test Key",
    "currentipvalid": true,
    "currentip": "",
    "overallstatus": true,
    "evaluation": false,
    "suspended": false,
    "emailvalidation": "Ok",
    "mobilevalidation": "Ok",
    "countriesavailable": "UK",
    "eircode": "No Access",
    "addressbase": "No Access",
    "emailvalidationaccess": "Full Access",
    "mobilevalidationaccess": "Full Access"

Request: - View live response

<Status xmlns:xsd="" xmlns:xsi="">
    <state>Test Key</state>
    <eircode>No Access</eircode>
    <addressbase>No Access</addressbase>
    <emailvalidationaccess>Full Access</emailvalidationaccess>
    <mobilevalidationaccess>Full Access</mobilevalidationaccess>

Response field descriptions

Field name Data type Description Example
correctsearchkey Boolean Flag to confirm whether or not the search key exists true
availablecredits Integer Number of search credits remaining 99999
lookupservicesup Boolean Flag to confirm the service is up and running true
state String Current status of the service and / or your account Ok
currentipvalid Boolean Flag to confirm whether the current IP address is authorised to make lookups true
currentip String IP address of the device making this request
overallstatus Boolean Flag to confirm the overall status of the service true
evaluation Boolean Flag to confirm whether this is an evaluation account false
suspended Boolean Flag to confirm whether this search key has been switched off false
emailvalidation String Current status of the email validation service Ok
mobilevalidation String Current status of the mobile validation service Ok
countriesavailable String Describes which countries are available to this search key ALL
eircode String This search key's level of access to Eircode data No Access
addressbase String This search key's level of access to AddressBase Premium data Full Access
emailvalidationaccess String This search key's level of access to the email validation service No Access
mobilevalidationaccess String This search key's level of access to the mobile validation service Full Access

To access AddressBase Premium or Eircode data using your API key, please contact us.