API Response - Error codes and messages

Introduction

Findaport API provides descriptive error outputs, normally consisting of an Error Code and accompanying Error Message.

The format of the error output is generally same as the requesting format. This is the case for XML and JSON requests.

There are two exceptions to the above:

Unrecognised API calls of any format are returned with HTTP status code 404 and a plain text error message.
HTML requests are returned with the error message in plain text, as we believe this is easier to parse.

Table of Error Conditions

Error Condition	Description	HTTP Status Code	Error Code	Error Message
Bad API call	Incorrect API call URL	404	10	Error code 10: The requested API call does not exist
API key - Not Supplied		200	11	No API key supplied
API key - Invalid		200	11	API key is invalid
API key - Expired		200	12	Your API key has expired
API key - Out of IP Range		200	13	Your IP address doesn't fall within the allowed IP range for this API key
API key - suspended		200	14	Your API key has been suspended
Usage - Throttled		200	21	You've been throttled for unusually high usage.
Invalid Resource ID	Invalid ID for Port, Country, ACE report etc.	200	30	Various depending on requested resource type
Invalid Sub-resource Name	e.g. when requesting Port Section	200	31
cdserial not provided	e.g. when FindaportCD is in Trial mode	200	41	cdserial parameter cannot be empty
cdserial invalid	e.g. an invalid CD Serial No. has been provided by FindaportCD	200	42	Invalid cdserial
No search results found		200	50	Your search returned no results. Please try changing your search criteria
Search Results maximum reached		200	51	Your search would have returned {{search_results}} results which is more than the maximum allowed results of {{max_results}} per request. Please use the 'results' param to limit the results returned. e.g. 'results={{max_results}}' Editable in settings under name of 'search_results_limit_error_msg'
Search paging out of range		200	52	Your requested results page of {{page}} doesn't exist. Your search has {{search_results}} search results and at {{results_per_page}} per page, there are a total of {{pages}} pages. Please lower your 'page' param to be less than or equal to {{pages}}. Editable in settings under name of 'search_page_out_of_range_msg'.

Error Output Formats

In XML

<error>

<code>[numerical error code]</code>
<message>[descriptive error message</message>

</error>

In JSON

{
    "error": { "code": [numerical error code],
               "message":"[descriptive error message]" }
}

Error Examples

{
   "error":{
      "code":21,
      "message":"Your usage has been throttled due to high activity. Please wait and try again later.\r\n                                                    \r\n See our \u003ca href=\"http://www.findaport.com/faq#usage_throttled\"\u003eFAQ\u003c/a\u003e for more information."
   }
}

Wiki