Modelo de errores

Para ayudar a los socios a diagnosticar y resolver problemas rápidamente, todas las APIs devuelven una respuesta de error estructurada. Este modelo es consistente en todos los endpoints e incluye suficiente contexto para depuración, sin exponer detalles internos.

Estructura del error

Cada respuesta de error sigue el mismo formato básico:

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

donde

code: Un identificador único y estable para el error.
title: Un resumen breve de lo que salió mal.
message: Un mensaje legible para humanos que explica cómo solucionarlo.

Usa siempre el campo code para identificar errores programáticamente. Los títulos y mensajes pueden evolucionar para mejorar la claridad.

Errores de validación a nivel de campo

Cuando un problema está relacionado con campos específicos en la carga útil de la solicitud, la respuesta incluye un objeto fields con información más granular.

Ejemplos

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

Formato de códigos de error

Todos los códigos de error siguen un formato estandarizado para simplificar la depuración y la trazabilidad entre plugins:

<XXX-NNNN>

Donde:

XXX es un prefijo de tres letras que identifica el plugin (ej., IDE para Identity, CRM para CRM).
NNNN es un número de cuatro dígitos único para el error.

Ejemplo: IDE-0001 — Campo requerido faltante en el plugin Identity

Asegúrate de que todos los errores personalizados sigan esta estructura para mantener la consistencia en todo el ecosistema.

​Estructura del error

​Errores de validación a nivel de campo

​Ejemplos

​Formato de códigos de error

Estructura del error

Errores de validación a nivel de campo

Ejemplos

Formato de códigos de error