Error responses resulting from an API request are indicated primarily through HTTP status codes. Expected errors are indicated with an HTTP status in the 400-499 range (inclusive), and usually indicate a problem with the request. Unexpected errors are in the 500-599 range (inclusive), and usually indicate a problem within the API service itself. For most error responses, additional information in the standardized JSON:API errors format is returned in the HTTP response body. An
"errors" key under the top level JSON object points to an array of error objects. At least one error object is returned in each error response. Each error object has, at minimum, the following 3 attributes:
A short description of the error.
The HTTP status code indicated by the error, formatted as a string.
A longer description of the error with greater detail than the
In addition, some error objects contain additional fields:
A JSON object containing a field under the key
An error code specific to this API. This information is primarily intended for internal diagnostic purposes.
The following table lists HTTP statuses returned by the API and their meanings. If you have used an HTTP-based API before, these may be familiar to you.
Your request was processed successfully. This is the standard success response for most requests.
Your request was processed successfully, and a new resource was created as a result. This is the standard success response for POST requests.
The API request was processed successfully, and no content is returned in the body. This is the standard success response for DELETE requests
The request was not structured correctly. The request body couldn't be parsed as valid JSON, or at least one required field in the query parameters or request body is missing, or the data in one of those fields could not be parsed as the correct data type. For example, putting data in a boolean field that isn't either
The request is not authorized. This is the standard error response whenever the
The request asked for something the API understands, but cannot accommodate. For example, trying to include a value for a resource's primary
The requested resource does not exist. This is most commonly encountered when trying to access or modify a resource with a particular id, when that id does not match any resource.
An existing resource conflicts with the request. For example, trying to create a Product Image resource with
The request was structured correctly, but could not be completed due to invalid data. For example, passing the empty string
Too Many Requests
Your request wasn't successful; too many requests have been sent within a particular span of time. See the API Rate Limit section for more details.
Internal Server Error
The API encountered an internal error and could not complete the request. This is usually indicative of an internal bug in the API, so if you ever see a 500 error, please reach out right away! We monitor 500 responses closely, and should be automatically notified of the problem, but user reports that include the request that caused the error can help us diagnose the problem more quickly, and are very much appreciated.
The API encountered an error from an upstream server while processing your request. This is usually indicative of a bug in a different API.
Updated about 2 years ago