Error Handling

Error Handling

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:

attribute keydata typedescription
"title"stringA short description of the error.
"status"stringthe HTTP status code indicated by the error, formatted as a string.
"detail"stringA longer description of the error with greater detail than the "title" description.

In addition, some error objects contain additional fields:

attribute keydata typedescription
"source"objectA JSON object containing a field under the key "pointer" that holds a JSON Pointer to the source of the error in the request body. For example, the JSON pointer "/data/relationships/organization" indicates an error inside the value under the key "organization" which is itself under the key "relationships", which is under the top level "data" key in the request.
"code"stringAn 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.

200OKYour request was processed successfully. This is the standard success response for most requests.
201CreatedYour request was processed successfully, and a new resource was created as a result. This is the standard success response for POST requests.
204No ContentThe API request was processed successfully, and no content is returned in the body. This is the standard success response for DELETE requests.
400Bad RequestThe 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 true or false results in a 400 error. NOTE: If you receive this status code during the OAuth token exchange process, then an invalid code parameter is provided in the request.
401UnauthorizedThe request is not authorized. This is the standard error response whenever the Authorization HTTP header is missing from a request, or if the credentials it contains could not be verified, or if the user does not have permission to perform the action they're requesting.
403ForbiddenThe request asked for something the API understands, but cannot accomodate. For example, trying to include a value for a resource's primary id field as an attribute on a POST request returns 403, because the id field is automatically generated by the API and cannot be specified by the user. NOTE: Check the response payload and ensure the request includes the appropriate scope for this action.
404Not FoundThe 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.
406Not AcceptableThe HTTP Content-Type or Accept headers on the request are not set to the specific value required by the JSON:API content negotiation specification, which is application/vnd.api+json. Other content types are not supported by the API.
409ConflictAn existing resource conflicts with the request. For example, trying to create a Product Image resource with is_primary set to true will return 409 when another primary image exists for that product, because products can have only one primary image at a time. NOTE: This error is usually associated with a PUT request. Ensure the request includes data that is newer than what's already on the server.
422Unprocessable EntityThe request was structured correctly, but could not be completed due to invalid data. For example, passing the empty string "" in place of a valid UUID for a required value in a request, results in a 422 error.
429Too Many RequestsYour 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.
500Internal Server ErrorThe 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 let us know 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.
502Bad GatewayThe API encountered an error from an upstream server while processing your request. This is usually indicative of a bug in a different API.