API v1 · Referencia
Errores y códigos de estado
Todos los endpoints comparten el mismo contrato de error: un status HTTP semántico y un cuerpo JSON uniforme. Nunca se exponen stack traces, queries ni mensajes internos de la base de datos.
Cuerpo de error
{
"error": "Parámetros inválidos",
"code": "invalid_params" // opcional: identificador estable del error
}Códigos de estado
OK
Petición exitosa.
Creado
Recurso creado (por ejemplo POST de wishlists o direcciones).
Solicitud inválida
Parámetros, query o cuerpo inválidos (falló la validación). El cuerpo trae un mensaje genérico, sin filtrar detalles internos.
No autenticado
Falta el header Authorization, o el token es inválido, expiró o fue revocado.
Sin acceso
La cuenta no está habilitada (gate de distribuidor) o al token le falta el scope requerido.
No encontrado
El recurso solicitado no existe.
Método no permitido
El método HTTP no aplica a esa ruta (respuesta automática con header Allow).
Demasiadas solicitudes
Se superó el límite de tasa. Respeta el header Retry-After (segundos) antes de reintentar.
Error interno
Error no controlado del servidor. No se exponen detalles.
No implementado
Funcionalidad deshabilitada por configuración (por ejemplo, la escritura de carrito).
Límite de tasa
Las peticiones están limitadas por cliente. Al excederse, la API responde 429 con el header Retry-After indicando los segundos a esperar. La emisión de token (POST /api/v1/oauth/token) tiene un límite más estricto.