Errores y límites de uso
Interpreta los errores HTTP, utiliza request_id para diagnosticar llamadas y aplica reintentos respetando los límites de Ecommerce Data API.
Formato de los errores
Los errores utilizan una estructura pública común. Los nombres de los campos y los mensajes de la API no cambian con el idioma de la documentación.
{
"request_id": "8fb43e59-4ff9-4dc8-a4b7-2ed164e45ab8",
"error": {
"code": "VALIDATION_ERROR",
"message": "One or more request fields are invalid.",
"details": [
{
"path": "asin",
"message": "Must be a valid 10-character ASIN"
}
]
}
}request_id identifica la llamada. error.code permite decidir cómo actuar desde el código; error.message describe el error. details solo aparece cuando hay información de validación por campo. En el ejemplo, details[].path indica que debes corregir asin antes de volver a enviar la solicitud.
Códigos de estado HTTP
| Estado | Significado |
|---|---|
400 | JSON o parámetros de solicitud no válidos. |
401 | Clave API ausente, no válida o caducada. |
402 | Créditos insuficientes. |
403 | Se requiere acceso mediante un plan, el acceso está inactivo o el endpoint no está incluido. |
413 | El cuerpo de la solicitud supera 64 KB. |
429 | Se ha superado un límite de la cuenta o del endpoint. |
500 | Error inesperado del servicio de API. |
502 | Falló la consulta de datos o devolvió una respuesta no válida. |
503 | Servicio no disponible, ocupado o sin configurar. |
504 | Se agotó el tiempo de espera del servicio de datos. |
Los códigos frecuentes son INVALID_JSON, VALIDATION_ERROR, API_KEY_REQUIRED, INVALID_API_KEY, API_KEY_EXPIRED, SUBSCRIPTION_REQUIRED, SUBSCRIPTION_INACTIVE, ENDPOINT_NOT_INCLUDED, RATE_LIMIT_EXCEEDED, CONCURRENCY_LIMIT_EXCEEDED, INSUFFICIENT_CREDITS, USAGE_LIMIT_EXCEEDED, SERVICE_BUSY, SERVICE_TIMEOUT y SERVICE_UNAVAILABLE.
Los límites por minuto, la concurrencia y los créditos de usuarios directos se aplican a la cuenta. Crear claves API adicionales no aumenta la cuota disponible.
Cabeceras de límites
Las respuestas pueden incluir las siguientes cabeceras; no asumas que siempre estarán presentes.
| Cabecera | Descripción |
|---|---|
X-RateLimit-Limit | Solicitudes permitidas en la ventana activa de un minuto. |
X-RateLimit-Remaining | Solicitudes que quedan en esa ventana. |
X-RateLimit-Reset | Momento de reinicio como marca de tiempo Unix en segundos. |
Retry-After | Segundos de espera antes de reintentar una solicitud limitada o con el servicio ocupado. |
X-Request-Id | Identificador de la solicitud a Ecommerce Data API. |
Política de reintentos
Para 429, 503 y 504, respeta Retry-After y utiliza espera exponencial con un pequeño componente aleatorio. Limita el número de intentos para evitar bucles y registra el request_id de cada intento. Si el problema persiste, detén los reintentos y consulta el estado del servicio o solicita soporte.
No repitas automáticamente errores de validación o autenticación sin corregir la solicitud. Un 402 requiere revisar los créditos; un 403, los permisos. Un nuevo intento es una nueva llamada: no deduzcas el resultado de una llamada anterior únicamente porque tu cliente haya agotado su tiempo de espera.
Historial y diagnóstico
Los usuarios que han iniciado sesión pueden consultar los metadatos de sus llamadas en el panel de uso. Se conservan durante 7 días los cuerpos de solicitud saneados y hasta 20 KB del contenido de respuesta. Los secretos y campos personales se ocultan antes de almacenarlos; el historial puede no contener la respuesta completa.
Al solicitar ayuda, indica el request_id, el endpoint, la hora y el código de error. No envíes claves API ni cabeceras de autorización. Consulta también Autenticación y Primeros pasos.