Common Response elements

Each end point will return data relevant to itself, but there will also always be a result dictionary containing the result of your request. This is where you look to see whether your request worked. If there was a problem you'll find a description of the problem here too.

In this example, you can see that the message and message_code are from the Detect end point, but there is the common code key which will be either success or error.

Key	Possible Values	Description
code	success error	A machine readable message that tells you whether your request was sent correctly and whether we handled it properly, or if there was some kind of problem on either end. Look at the message/message_code fields for more detail.
message	Varies by end-point	A human readable message that tells you specifically how your request was handled by the API.
message_code	Varies by end-point	A machine readable message that tells you specifically how your request was handled by the API.

The message fields

The message and message_code fields in the API response's result key will give you more detail about how your request was handled.

Generally speaking, if your request was successful, they will be something relating to your end point (eg. "The processing was completed"). If there was some kind of problem the message will tell you more about the problem (eg. "No headers were provided in the request"; or it may also be a more general kind of error: "No X-API-KEY header provided in the request".)

Message and Message Code

Inside the result key, the message key will contain a human readable message which is constructed for developers to read and get a better understanding of your request result, as well as this the message_code is specifically built for your software to inspect.

For example, your code can look for and handle scenarios like a message_code being usage_limit_exceeded, and know to not send any more API requests until the next month.

Your code should never inspect the contents of message and make decisions based on it. Instead: your code should look at message_code.

While we're always very careful... a human readable message string can still theoretically change - perhaps a minor punctuation correction, or meaningful clarification...

However message_code is specifically built to never change, so if your code checks for certain values, you can be assured that it will always work the same way.

Common message_code values

The following table doesn't show all of the message codes which the API can return. Each endpoint has one or more message/message codes when your request was successful. Those endpoints will also have some "error" messages/messages codes specific to them as well. Make sure to read the documentation for those end points for more information.

Here is a list of the common error messages/message codes which the API may return. Similar to the "success" results, they will appear in the JSON result similar to this - for example:

Possible message_code when code is error

message_code	Description
api_system_error	Some kind of Server Side Error (500) has occurred.
invalid_api_version	Version 2 of the API is the latest version. So if you try to access an end point starting with /api/v3/ or higher you will get this error.
invalid_http_request_method	Your request was sent with the wrong method: Perhaps you sent it as a GET instead of a POST. (or maybe vice-versa)
missing_api_authentication	Your request didn't contain the X-API-KEY. Refer to Debugging Authentication.
usage_limit_exceeded	Your account has gone over your monthly quota for this end point.
api_authentication_invalid	The API Key sent in X-API-KEY was incorrect. Maybe you generated a new one? Get your API Key.
endpoint_not_available_for_this_api_version	Version 2 of the API has been deprecated (but not discontinued). However new end points will not be back-ported to Version 2. You are trying to access one of the new end points on an older version of the API.
endpoint_not_available_for_your_plan	You tried to access an API End Point that your plan doesn't have access to. Change your API Plan.
invalid_end_point	404 End Point not found. Check the URL.
invalid_json	We couldn't decode valid JSON from your request. Help with debugging JSON issues.

HTTP Status Codes

As well as returning result messages and codes, we also return meaningful HTTP Status Codes.

Status Code	Name	Description
200	Success	We handled your request successfully.
400	Bad request	There was something wrong with your request. Check the "message" fields for more information.
401	Invalid API Key	Your API Key is wrong. Get your API Key.
403	Quota exceeded	You have gone over your monthly limit. Monitor API usage.
404	Not Found	The End Point URL you requested was incorrect.
405	Wrong method	You did something like send a GET instead of a POST (or maybe a POST instead of a GET)
500	Server Error	We've had some kind of error on our end.

Common errors

End point not available for your plan

If you send a valid API Key but your account's plan does not have access to the specified end point, you will receive a response like:

You will get this kind of response if you do something like try to access the Versions End Point on the Basic tier.

If you want permission to access to the end point you're trying to use, you can upgrade your API Plan.

Usage Limit Exceeded

If you send a valid API key but your account has gone over it's monthly limit for this end point, you will receive a response like:

Note that end points are metered independently of each other; so you might have exceeded the limit of one end point but can still use other ones.

You can monitor your account usage in the Accounts System -> View API Usage.

We will send you warning emails when you are at 90% and 100% of your limits.