Gestión de errores

Todos los errores devuelven un cuerpo JSON consistente, independientemente del endpoint.

Formato

error_code — código estable que puedes usar para manejar el error programáticamente.
message — descripción legible del error.
errors — opcional; detalle por campo en errores de validación.

shell

{
  "error_code": "VALIDATION_ERROR",
  "message": "El campo \"email\" es obligatorio",
  "errors": {
    "email": "required"
  }
}

Códigos de estado

Estado	Significado
400	Petición inválida (validación de campos)
401	Clave ausente, inválida o revocada
403	La clave no tiene el scope necesario
404	El recurso no existe (o no pertenece a tu tenant)
409	Conflicto — el recurso ya existe o el estado no lo permite
422	Regla de negocio incumplida (p. ej. sin disponibilidad)
429	Límite de peticiones excedido — ver Límites
500	Error interno; reintenta más tarde

Estrategia de reintentos

Reintenta con espera exponencial ante 429, 502, 503 y 504. No reintentes automáticamente ante 4xx distintos de 429: son errores de tu petición y se repetirán igual.