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.