Saltar al contenido principal
Cuando algo sale mal, la API devuelve un status HTTP de error (4xx/5xx) y un cuerpo JSON en el formato estándar que se muestra a continuación.

​
Formato del error

{
  "error": {
    "code": "CONFLICT",
    "message": "E-mail já cadastrado",
    "key": "errors.conflict.duplicate_email",
    "params": { "email": "joao@example.com" },
    "details": { }
  }
}
CampoSiempre presenteDescripción
codeSíCódigo estable legible por máquina (ej.: NOT_FOUND, VALIDATION_ERROR).
messageSíMensaje legible por humanos (fallback en pt-BR).
keyNoClave de i18n, cuando el mensaje es traducible.
paramsNoParámetros de interpolación del mensaje (ej.: { "email": "..." }).
detailsNoDetalles adicionales (ej.: errores por campo en la validación).
Programe su lógica en base al code (y al status HTTP), nunca en el texto de message — el texto puede cambiar o llegar traducido.

​
Códigos HTTP

StatusCódigo típicoSignificadoQué hacer
400VALIDATION_ERRORCuerpo/parámetros inválidos.Corregir el payload. Ver details.
401UNAUTHORIZEDAPI key ausente o inválida.Verificar el header x-api-key.
403FORBIDDENSin permiso para la operación.Verificar el tipo/scope de la clave.
404NOT_FOUNDEl recurso no existe (o pertenece a otra cuenta).Verificar el ID.
409CONFLICTConflicto de estado (duplicado, transición inválida).Manejar el caso específico.
422UNPROCESSABLE_ENTITYSolicitud comprendida, pero no procesable.Revisar la regla de negocio.
429RATE_LIMIT_EXCEEDEDLímite de solicitudes excedido.Esperar y reintentar con backoff.
500 / 502 / 503INTERNAL_ERRORError en el servidor.Reintentar con backoff; si persiste, contactar soporte.

​
Errores de validación (400)

Cuando uno o más campos son inválidos, details contiene el mensaje por campo: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validação",
    "details": {
      "items": "É necessário pelo menos 1 item",
      "payments": "Soma dos payments (5000) deve ser igual ao total dos items (4990)"
    }
  }
}

​
Manejo recomendado

Retry con backoff

En 429 y 5xx, reintente con backoff exponencial. Combine con Idempotency-Key para no duplicar la operación.

No haga retry en 4xx

400/409/422 no se resuelven reintentando — corrija la solicitud.

Registre el code y el request id

Guarde code, status y el cuerpo para diagnóstico. No registre la API key.

Idempotencia siempre

En escrituras, use Idempotency-Key para que los retries sean seguros. Ver Convenciones.