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 Key	Data Type	Description
title	string	A short description of the error.
status	string	The HTTP status code indicated by the error, formatted as a string.
detail	string	A longer description of the error with greater detail than the `"title"` description.

In addition, some error objects contain additional fields:

Attribute Key	Data Type	Description
source	object	A 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	string	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.

Status	Name	Meaning
200	OK	Your request was processed successfully. This is the standard success response for most requests.
201	Created	Your request was processed successfully, and a new resource was created as a result. This is the standard success response for POST requests.
204	No Content	The API request was processed successfully, and no content is returned in the body. This is the standard success response for DELETE requests
400	Bad Request	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 `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.
401	Unauthorized	The 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.
403	Forbidden	The request asked for something the API understands, but cannot accommodate. 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.
404	Not Found	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.
406	Not Acceptable	The 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.
409	Conflict	An 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.
422	Unprocessable Entity	The 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.
429	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.
500	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.
502	Bad Gateway	The API encountered an error from an upstream server while processing your request. This is usually indicative of a bug in a different API.