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.
||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 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".)
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.
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:
|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.|
As well as returning result messages and codes, we also return meaningful HTTP Status Codes.
|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.|
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.
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.