Manejo de errores

Todos los errores siguen el mismo formato:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "product with id '...' not found"
  }
}

Códigos HTTP

Status	Cuándo ocurre
400 Bad Request	Request malformado o parámetros inválidos
401 Unauthorized	Token ausente o expirado
403 Forbidden	Sin permisos para esta operación
404 Not Found	Recurso no encontrado
409 Conflict	Conflicto (slug duplicado, etc.)
422 Unprocessable Entity	Validación de negocio falló
429 Too Many Requests	Rate limit alcanzado
500 Internal Server Error	Error del servidor

Códigos de error internos

code	Descripción
RESOURCE_NOT_FOUND	El recurso solicitado no existe
VALIDATION_ERROR	Uno o más campos fallaron validación
DUPLICATE_SLUG	El slug ya existe para este tenant
PLAN_LIMIT_EXCEEDED	Límite del plan alcanzado (productos, órdenes)
UNAUTHORIZED	Autenticación requerida
FORBIDDEN	Sin permisos suficientes
INTERNAL_ERROR	Error interno — reporta en soporte

Rate limiting

Los headers de rate limit se incluyen en cada respuesta:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1712534400

Cuando llegues al límite recibirás 429 — espera hasta X-RateLimit-Reset (Unix timestamp).