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

Error object structure

Every error response follows the same basic format:

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

Field definitions

• 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.

👍

Tip

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.

Example: Missing required fields

{
  "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"
  }
}

Example: Invalid field values

{
  "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"
  }
}

Example: Unexpected fields

{
  "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

📘

Note

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