API Error Responses

This page explains how errors are returned by the REST API.

For shared REST API environment and authentication requirements, see REST API Overview.

Error response categories

1) Structured custom error responses

Many API errors use the following structured format:

{
  "type": "<error_type>",
  "errors": [
    {
      "code": "<error_code>",
      "detail": "<human readable message>",
      "attr": "<field path or null>"
    }
  ]
}

• type identifies the error category (for example, validation_error or client_error).
• errors is a list.
• Each error item contains:
  • code
  • detail
  • attr
• attr can be null when the error is not tied to a specific field.

2) Validation errors

Validation failures also follow the same structured schema, typically with:

• type: "validation_error"
• field-level attr values (for example, contact_ids)

Example:

{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "detail": "This field is required.",
      "attr": "contact_ids"
    }
  ]
}

3) Empty 403 Forbidden responses

When the API returns 403 Forbidden, the response body is empty.

Only the HTTP status code is returned.