Once you have made a request to the API, there are a number of responses you may receive. We have worked hard to make the API as simplistic as possible to use, so you should only receive the addresses for the postcodes have looked up, however, we also have some simple error messages for if anything does go wrong. All of our responses are sent as JSON data and include your remianing calls that day, and remaining credits for your current month, as well as a Success/Failure response, and releated http code (this also gets sent as a http header).
Successful response
{
"result": "Success",
"callsRemaining": 2928,
"creditsRemaining": 74928,
"latitude": "51.503540",
"longitude": "-0.127695",
"expandedAddress": {
"house": "10",
"street": "Downing street",
"locality": "",
"town": "London",
"district": "Greater london",
"county": "London",
"pCode": "SW1A 2AA"
},
"csvAddress": "10,Downing street,,London,Greater london,London,SW1A 2AA",
"statusCode": "200"
}
Invalid postcode
This is the response you would get if you enter a postcode that is invalid. We cross reference numerous databases for validity of a postcode, and even have defunct postcodes within our database, as well as redundancies for any postcodes we may be missing, so if you are receiving this during an address lookup, please check the postcode is correct. It is
strongly recommended to remove spaces from the house and postcode strings, however using a "+" is also allowed. Failure to remove spaces or replace them with a "+" will result in a server side 403 error due to our servers security configuration.
{
"result": "Failure",
"callsRemaining": "2913",
"creditsRemaining": "74913",
"errorMsg": "Postal Code Not Valid",
"statusCode": "400"
}
Unauthorised access
This the response you will receive if you are missing or have incorrect information in your API key or user agent information, or if you do not have a subcription.
{
"result": "Failure",
"errorMsg": "Unauthorised access",
"statusCode": "401"
}
Exceeded limit responses
These are the two responses you may receive if you have exceeded your subscription daily or monthly limits.
{
"result": "Failure",
"errorMsg": "You have exceeded your daily limit",
"statusCode": "429"
}
{
"result": "Failure",
"errorMsg": "You have exceeded your monthly limit",
"statusCode": "429"
}
Subscription lapsed
If you have not cancelled, or not renewed your subscription, it will continue until your current months end date, after that, you will receive the follwing message when trying to make a call to the API.
{
"result": "Failure",
"errorMsg": "Your subscription ended on 25-04-2024",
"statusCode": "401"
}
Database error
If you receive this response, something has gone wrong at our end. Most likely we are already correcting something, or updating something to make your experience better. But it's best to contact us to check!
{
"result": "Failure",
"errorMsg": "Database Error #errNo. - Please contact support @ findaddress.io",
"statusCode": "500"
}