Contrato objetivo (en convergencia)

Este es el formato de error estándar al que se apega la API. Durante la migración, algunos endpoints pueden devolver todavía una forma distinta; programa tu manejo de errores contra este contrato y apóyate siempre en el código de estado HTTP.

La API usa códigos de estado HTTP estándar: 2xx indica éxito, 4xx un problema con la petición (credenciales, permisos o datos) y 5xx un error del servidor.

Formato de error

Los errores se devuelven en un arreglo errors (estilo JSON:API). Cada error incluye el status HTTP, un code legible por máquina, un title general y un detail específico. Los errores de validación agregan source.pointer con el campo afectado.

Error 422 · validación

{
  "errors": [
    {
      "status": "422",
      "code": "validation_error",
      "title": "Dato inválido",
      "detail": "El código de artículo ya está en uso.",
      "source": { "pointer": "/data/attributes/item_code" }
    }
  ]
}

Cada respuesta de error incluye además el header X-Request-Id. Inclúyelo cuando reportes un problema para que podamos rastrear la llamada exacta.

Códigos de estado

HTTP	`code`	Significado
200	—	OK — la solicitud se procesó.
201	—	Created — se creó el recurso.
204	—	No Content — éxito sin cuerpo (por ejemplo, al eliminar).
400	bad_request	La petición está mal formada.
401	unauthenticated	Falta el token o es inválido/expiró.
403	forbidden	La API no está habilitada para el tenant, o el token no tiene el permiso requerido.
404	not_found	El recurso no existe.
422	validation_error	Falló la validación de los datos enviados.
429	rate_limited	Superaste el límite de tasa (ver Convenciones).
500	server_error	Error del servidor. Si persiste, contáctanos con el `X-Request-Id`.

Ejemplos

401 · no autenticado

{
  "errors": [
    { "status": "401", "code": "unauthenticated", "title": "No autenticado", "detail": "El token es inválido o expiró." }
  ]
}

404 · no encontrado

{
  "errors": [
    { "status": "404", "code": "not_found", "title": "No encontrado", "detail": "El producto solicitado no existe." }
  ]
}

Un 403 puede significar dos cosas: la API pública no está habilitada para tu tenant, o tu token no tiene el permiso de la operación. Revisa Acceso y habilitación.