Errores

Todo rechazo responde con el formato RFC 9457 (Content-Type: application/problem+json) y un code estable que podés usar en tu código. El title está en castellano y se puede mostrar tal cual a una persona.

{
  "type": "urn:erp:problem:input.invalid",
  "title": "Hay datos inválidos",
  "status": 422,
  "code": "input.invalid",
  "errors": [{ "field": "lines.0.quantity", "message": "La cantidad tiene que ser mayor que cero." }]
}

Campo	Qué es
code	Código estable módulo.motivo. Es lo que tu integración compara.
status	El mismo código HTTP de la respuesta.
title	Qué pasó, en castellano, para mostrar.
detail	Más contexto, cuando lo hay.
errors	En datos inválidos, el campo y el mensaje de cada error.
retryAfterSeconds	En un rechazo transitorio, cuántos segundos esperar. También va en Retry-After.

Códigos comunes

Código	HTTP	Qué pasó	Qué hacer
session.required	401	Falta la credencial o venció.	Volvé a autenticarte.
permission.denied	403	La credencial no tiene el permiso de la operación.	Pedí el permiso al administrador.
operation.unavailable	404	La operación no se ofrece por este canal.	Usá otra operación.
idempotency.key-required	400	Falta la Idempotency-Key en una escritura.	Mandá una clave por intento.
idempotency.key-reused	422	La clave ya se usó con otra operación o con otros datos.	Generá una clave nueva.
input.invalid	422	Hay datos inválidos; el detalle está en errors.	Corregí los campos indicados.
company.expected-required	428	Falta X-Expected-Company.	Mandá el id de la empresa.
company.no-active	409	La sesión no tiene empresa activa.	Elegí la empresa activa.
company.mismatch	409	La empresa activa no es la esperada.	Revisá la empresa y volvé a leer.
record.stale	409	Otra persona cambió el registro desde que lo leíste.	Volvé a leerlo y reintentá con la versión nueva.
database.busy	503	El sistema está ocupado.	Reintentá después de Retry-After.
internal	500	Error interno, sin detalle.	Reintentá; si sigue, avisá a soporte.

Reglas de negocio

Cuando una operación rompe una regla del negocio, el código es del módulo: por ejemplo sales-orders.not-found (404) o un conflicto de estado (409). El title siempre explica qué pasó en palabras.