8 Error Responses

RESTful Best Practices

8.1 Error payloads 

8.1.1 All Errors

All errors MUST comply with Problem Details RFC (RFC-7807) format.

An error response SHOULD constrain the title field to be a lowerCamelCase name of the error or a predefined code part of another RFC (ie, OAuth2).  The title field SHOULD be human readable and easily used as a key for localization.

An error response MAY include other fields specific to the error.

The following error information MAY be included. If it is included, it MUST use the fields as described:

• causes - array of error objects (e.g. when multiple things went wrong all at once, such as validation errors).  Each error should match the format of the Problem Details RFC.

The instance field MAY be a UUID URN, if no dereference-able URL exists for the instance (ex: "urn:uuid:b3aa9faf-58fd-47d0-a44c-8d943cda634b" )

Examples

Single error  Expand source

{
  "status": 400,
  "type": "https://errors.cimpress.io/invalidItemStatus",
  "title": "invalidItemStatus",
  "detail": "The specified status: 'kaput' is invalid for this item",
  "instance": "https://items.cimpress.io/errors/a3082d39-2b2c-4899-86b8-9f9b1a85d486"
}

Multiple causes for an Error  Expand source

{
  "status": 422,
  "type": "https://errors.cimpress.io/orders/failedValidation",
  "title": "orderFailedValidation",
  "detail": "Multiple errors occured when validating the order. See causes for more information",
  "instance": "urn:uuid:fc12d8b3-ee3c-476d-a395-49e8ead10084"
  "merchantOrderId": "abc-123-xyz",
  "causes": [
    {
      "type": "https://errors.cimpress.io/orders/validation/negativeQuantity",
      "title": "negativeQuantity",
      "detail": "Quantity cannot be a negative number",
      "merchantItemId": "5792381-qmu",
      "quantity": "-100"
    }, {
      "type": "https://errors.cimpress.io/orders/validation/invalidCountryCode",
      "title": "invalidCountryCode",
      "detail": "The Countrycode 'roflcopter' is not valid. Please provide an ISO 3166 alpha-2 country code.",
  }]
}

8.1.2 Authentication errors

Authentication errors SHOULD return a response in the problem details format.

We know we say to use lowerCamelCase for error code fields to match all of our other API casing standards, but the OAuth2 specification specifically require snake_case. Follow the industry standard for the specification to be compliant with the standard.

8.1.3 412 Precondition Failed

When returning a 412 Precondition Failed, an API SHOULD return an etag field when the update is rejected for a conflict. The etag MUST be the current version of the resource had a GET been requested instead of a PUT or PATCH.

Additional fields are a good idea for specific errors. Returning the etag on a version mismatch allows the caller to perform investigation about why their update failed.

412 Precondition Failed  Expand source

{
  "status": 412,
  "type": "https://errors.cimpress.io/itemConflict",
  "title": "itemConflict",
  "detail": "The update is unable to be applied to this item.  Get the latest version and resubmit.",
  "errorId": "urn:uuid:b3aa9faf-58fd-47d0-a44c-8d943cda634b",
  "etag":  "8ef4abc"
}