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.

"result": { "code": "success", "message_code": "detection_processed", "message": "The processing was completed" }

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
  • 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:

{ "result": { "code": "error", "message": "The plan your account is on (basic) does not have permission to access this API endpoint. Please upgrade to a plan which grants you access.", "message_code": "endpoint_not_available_for_your_plan" } }

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:

{ "result": { "code": "error", "message": "Your account has gone over its limit for this month. Please consider upgrading your plan.", "message_code": "usage_limit_exceeded" } }

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.