Error model

To help partners quickly diagnose and resolve issues, all APIs return a structured error response. This model is consistent across endpoints and includes enough context for debugging, without exposing internal details.

Error structure

Every error response follows the same basic format:

{
  "code": "<error_code>",
  "title": "<error_title>",
  "message": "<error_message>"
}

where

code: A unique, stable identifier for the error.
title: A brief summary of what went wrong.
message: A human-readable message explaining how to fix it.

Always use the code field to programmatically identify errors. Titles and messages may evolve to improve clarity.

Field-level validation errors

When an issue is related to specific fields in the request payload, the response includes a fields object with more granular information.

Examples

{
  "code": "IDE-0009",
  "title": "Missing Fields in Request",
  "message": "Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.",
  "fields": {
    "document": "document is a required field"
  }
}

{
  "code": "CRM-0047",
  "title": "Bad Request",
  "message": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
  "fields": {
    "legalName": "legalName is a required field.",
    "parentOrganizationId": "parentOrganizationId must be a valid UUID"
  }
}

{
  "code": "CRM-0053",
  "title": "Unexpected Fields in the Request",
  "message": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
  "fields": {
    "extraField": "extraField is not allowed"
  }
}

Error code format

All error codes follow a standardized format to simplify debugging and traceability across plugins:

<XXX-NNNN>

Where:

XXX is a three-letter prefix that identifies the plugin (e.g., IDE for Identity, CRM for CRM).
NNNN is a four-digit number unique to the error.

Example: IDE-0001 – Missing required field in the Identity plugin

Make sure all custom errors follow this structure to keep things consistent across the ecosystem.

Overview

Field dictionary

Error structure

Field-level validation errors

Examples

Error code format

​Error structure

​Field-level validation errors

​Examples

​Error code format

Error structure

Field-level validation errors

Examples

Error code format