Features Pricing FAQ API Docs Blog
Signup / Login
Select Page

Error Handling

Error Categories

Our API categorizes errors into two different and very distinct types: Client Side Errors and Server Side Errors. When a request first reach our servers, we do a ton of security, authentication and data validation checks. If any of these fail a Client Side Error is typically generated with a message detailing the error that took place.

Client Side Errors

Client Side Errors include everything that can cause incorrect execution due to user error(s). An example of user error would be forgetting to set the X-API-Key header which is required to authenticate the request. Another example would be providing invalid input data to one of the endpoint parameters.

// Make a request to an endpoint that does not exist

curl https://api.jsonrepo.com/{SOME_BAD_ENDPOINT} \
-H "X-API-Key: {YOUR_API_KEY_HERE}"
// Server Response

{
    "http_code": 404,
    "http_message": "Not Found",
    "message": "Requested route not found",
    "payload": []
}

When a Client Side Error is issued, our service will pick one of the HTTP error codes enumerated in the table at the bottom of this page.

Server Side Errors

Server Side Errors often indicate incorrect execution of the request based on the provided user input. In order to protect our servers from malicious use, we have strict rules in place that cut off execution. All of these errors are reported with a 500 HTTP code. If you encounter such an error, please report it to us as soon as possible using one of our customer support channels: Twitter, Discord or Email.

HTTP Codes

Code Status Description
200 Ok Request was successful.
400 Bad Request Issued when a request is incomplete, has missing field(s) or badly formatted input data.
401 Unauthorized Issued when X-API-Key is not provided or is invalid.
402 Payment Required Issued when the account does not have sufficient funds to execute the request. For more info about our pricing model see this page.
403 Forbidden Issued when trying to access a resource before verifying the email associated with the account.
404 Not Found Issued when the request is trying to reach an endpoint that does not exist.
405 Method Not Allowed Issued when the request is using the incorrect HTTP verb. Our endpoints mostly use GET and POST.
409 Conflict Issued when the request is attempting to change a record that's marked as final.
500 Server Side Error Issued when the server halts execution. If ever encountered, please make sure to report it to us asap.
503 Service Unavailable Issued when the endpoint is down for maintenance.