Errors

Here is how Cooler API returns errors to consuming APIs

The Cooler API uses conventional HTTP response codes to indicate a success or failure operation for an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed to process correctly, likely due to invalid data inputs or an invalid business operation that was triggered. Codes in the 5xx range indicate a critical/system-wide error with Cooler servers processing the requests. Our support team is available 24/7 for assistance if these issues persist.

Some 4xx errors can be handled programmatically and will include error codes to give context to what the error is reporting. When this happens, the API will respond with a JSON object in the response body with an errors array of one or more error objects that contain contextual information.

Each of these error objects will contain a code (such as "NOT_FOUND") and, optionally, a detail (such as "Unable to calculate the footprint for this item."). The code is stable and can be used in your code. The detail is not necessarily stable and is for you, the developer. We may change the string to make the message more descriptive, for example. For example, here’s what an authentication error response might look like:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "errors": {
    "code": "UNAUTHORIZED",
    "detail": "No authentication was provided."
  }
}

The errors array may contain more than 1 error object. If there are multiple errors in the errors array and none of them are INTERNAL_SERVER_ERRORs, the HTTP status code will always be 400. If any of the errors are INTERNAL_SERVER_ERROR, the HTTP status code will be 500.

Many errors are endpoint-specific, but the following can apply to any request:

HTTP Code	Description
400	Something about the HTTP request is malformed. This is usually an indicator of an HTTP-level problem, not an application-level problem. This can happen if we failed to parse a request body as JSON, if you sent less data than you indicated with Content-Length, or for other reasons.
401	Authorization failed for some reason. You may have failed to send the Cooler-API-Key header, it may be malformatted, or the API key may be invalid.
404	Among other reasons, you can receive this error if the endpoint is not found.
406	Accept header is set and does not accept application/json.
411	No Content-Length header was provided, or it was invalid.
413	The Content-Length header indicated a body larger than 100 kilobytes (102,400 bytes).
414	You made a request to a path that is longer than 1024 bytes. This includes the query string.
415	The request has a body and Content-Type is not application/json.
422	You sent us valid JSON, but it was invalid data for the endpoint. This can also happen if you send us invalid HTTP headers.
429	You have exceeded the API’s rate limit; try again later. See the “Rate limits” section of these docs for more info.
431	Your headers are too large. This can happen if one or more of your request’s HTTP headers is larger than 256 bytes (this includes header name and value), or if you sent too many headers total.
500	Cooler is having a problem. You may wish to retry your request.