Error Handling

Our API categorizes errors into 2 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 an associated HTTP code along 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 api_key header which is required to authenticate the request. Another example would be providing invalid input data to one of the endpoint parameters.

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 `api_key` is not provided or is invalid.
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`.
429	Too Many Requests	Issued when the `api_key` has reached its request limit. For more info about rate limits see our Pricing Plans.
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.

A Lorenum.com product

Twitter Discord Email

Bad Endpoint Request

Curl

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

curl \
https://api.jsonrepo.com/{SOME_BAD_ENDPOINT} \
-H "api_key: {YOUR_API_KEY_HERE}"

Server Response

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

Bad API KEY Request

Curl

// Make a request with an invalid API key

curl \
https://api.jsonrepo.com/{endpoint} \
-H "api_key: {BAD_API_KEY}"

Server Response

{
    "http_code": 401,
    "http_message": "Unauthorized",
    "message": "Malformed request: `api_key` is invalid",
    "payload": []
}