How to Handle an Error

Error scenarios include:

• Authorization and authentication failures.
• Submission of request content that does not conform to the API contract resulting in a Bad Request outcome.
• Internal processing errors.

Consuming our errors is a simple process designed to allow customers to self-serve and quickly get their integrations back in working condition.

HTTP status

Successful responses will provide you with a 2xx HTTP status code. Any HTTP status code >= 400 should be checked against our error schema.

Error schema

The body of an error response is a JSON object with an "errors" attribute. This contains an array of one or more error objects.

{
  "errors": [
    // error objects
  ]
}

Each error object contains "name" and "code" attributes unique to each error type. This will usually provide enough information to handle an error. Certain errors provide additional fields to indicate the part of the request that needs attention. These fields include "jsonBody", "pathParameter", "queryParameter" and "resourcePath".

Error attributes

Attribute	Format	Example	Description
"name"	Pascal case string.	"DatasetNotFound"	Unique error name.
"code"	5- or 6-digit numerical string.	"404002"	Unique error code.
"message"	String (prose).	"Dataset not found for id '99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B'."	Human-readable description of the error. Not to be relied on for integration logic.
Contextual Attributes
"pathParameter"	Camel case string inside curly braces.	"{datasetId}"	Identifier for the path parameter that is the subject of the error.
"queryParameter"	JSON path (without "$." prefix).	"dataset.drafts[0].draftId"	Identifier for the query parameter that is the subject of the error.
"jsonBody"	JSON path (with "$." prefix).	"$.dataset.drafts[0].draftId"	Identifier for the field of the JSON body that is the subject of the error.
"resourcePath"	Relative path.	"/EXAMPLE_TENANT/datasets/99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B"	Identifier for the resource that is the subject of the error.

All possible error names and codes can be found in the Full list of API errors.

The exact error schema can be inspected and downloaded as part of the full OpenAPI specification that makes up the API Reference.

Example

{
  "errors": [
    {
      "name": "DatasetNotFound",
      "code": "404002",
      "message": "Dataset not found for id '99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B'.",
      // additional field(s) depending on context
      "pathParameter": "{datasetId}",
      "resourcePath": "/EXAMPLE_TENANT/datasets/99020AB5-EFEC-BED1-FDC5-3DDF9ED9A59B"
    }
  ]
}

The human-readable "message"

The "message" attribute provides a brief plain English description of the error. The precise content might change without an update of API version.

note

Please do not rely on the "message" content for consuming an error. You should only check against "name" or "code" values.

Error limiting

In order to aid debugging we return as many errors as possible in a single response to avoid repeated API calls to see each 'next' error. However, there are situations in which large numbers of errors might be detected (for example, a long array with repeated invalid values). We therefore currently limit the number of instances of a particular error to 10 in our responses.