Errors

The Isaacus API uses conventional HTTP response codes to indicate whether an API request has successed or failed.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate a problem with the request that was sent, and codes in the 5xx range indicate an error with our servers.

Errors returned by our API servers (as opposed to errors generated by gateway servers) will conform to the RFC 7807 problem detail standard:

{
    "type": "A URL that explains the error or 'about:blank' if no such URL is available.",
    "title": "A short, human-readable summary of the problem.",
    "status": "The HTTP status code (normally 400 or 500) generated by the origin server for this occurrence of the problem.",
    "detail": "An optional human-readable explanation specific to this occurrence of the problem.",
    "instance": "An optional URL that identifies this specific occurrence of the problem."
}

​

Error types

This is a non-exhaustive list of the types of errors you may encounter when using the Isaacus API.

​

400 validation error

A validation error indicates that the API request was invalid, perhaps because a constraint was violated or a required field was missing, or perhaps because the request was incapable of being processed due to some quality of the request itself.

A validation error will return the 400 Bad Request status code.

A validation error should always include a non-generic detail field that explains, in some way, what was wrong with the request. If you ever encounter a validation error that does not include a detail field (or that lacks sufficient information to help you understand what went wrong with your request), please let us know.

​

401 unauthenticated error

An unauthenticated error indicates that the request was not properly authenticated. This is typically because the request used an API key that does not exist, is expired or is revoked.

An unauthenticated error will return the 401 Unauthorized status code.

If you encounter an unauthenticated error, please double-check that the API key you are using to make the request is correct and active. If you are certain that the API key is correct and active, please let us know.

​

402 payment required error

A payment required error indicates that the request was not processed because the account associated with the API key used to make the request has an outstanding balance. You can pay overdue invoices here.

A payment required error will return the 402 Payment Required status code.

If you encounter a payment required error but you have no outstanding balance, please let us know.

​

403 access forbidden error

An access forbidden error indicates that the request was not processed because the account associated with the API key used to make the request does not have permission to access the requested resource. This could be because you cancelled your subscription to our zero flat fee, usage-based API plan, which you can resubscribe to here.

An access forbidden error will return the 403 Forbidden status code.

If you encounter an access forbidden error but you have not unsubscribed from our API plan, please let us know.

​

404 not found error

A not found error indicates that the requested resource could not be found, either because it never existed or because it was deleted.

A not found error will return the 404 Not Found status code.

If you encounter a not found error, please double-check the URL you are using to make the request. If you are certain that the URL is correct, please let us know.

​

405 method not allowed error

A method not allowed error indicates that the request was made using a HTTP method that is not supported by the requested resource, for example, using a GET request to an endpoint that only supports POST requests.

A method not allowed error will return the 405 Method Not Allowed status code.

​

413 request too large error

A request too large error indicates that the request was too large for the server to process, typically because the request body exceeded the maximum size allowed by the server.

A request too large error will return the 413 Payload Too Large status code.

If you want to be able to send larger requests, please let us know.

​

500 internal server error

An internal server error indicates that the server encountered an unexpected problem that prevented it from fulfilling the request.

An internal server error will return the 500 Internal Server Error status code.

You are advised to try retrying your request if you encounter an internal server error. If the problem persists, please let us know, or else try waiting a bit later, as we are pinged whenever internal server errors occur and we may be in the process of fixing the problem.