Errors & Rate Limits
Understand Ecommerce Data API error responses, request IDs, and rate-limit headers.
Errors & Rate Limits
Error format
All errors use the same public structure:
{
"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"
}
]
}
}details is included when field-level validation information is available.
HTTP status codes
| Status | Meaning |
|---|---|
400 | Invalid JSON or request parameters |
401 | Missing, invalid, or expired API key |
402 | Insufficient Credits |
403 | Subscription required, inactive, or endpoint not included |
413 | Request body exceeds 64 KB |
429 | Account or endpoint rate limit exceeded |
500 | Unexpected gateway error |
502 | Data request failed or returned an invalid response |
503 | Service unavailable, busy, or not configured |
504 | Data service timeout |
Common error codes include 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, and SERVICE_UNAVAILABLE. RPM, concurrency, and Credits
for direct users are enforced at the account level, so creating additional API
keys does not increase the available quota.
Rate-limit headers
Responses can include:
| Header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed in the active minute window |
X-RateLimit-Remaining | Requests remaining in that window |
X-RateLimit-Reset | Window reset time as a Unix timestamp in seconds |
Retry-After | Seconds to wait before retrying a limited or busy request |
X-Request-Id | Ecommerce Data API request identifier |
Honor Retry-After and use exponential backoff with jitter for 429, 503,
and 504 responses. Do not retry validation or authentication failures without
changing the request.
Usage details
Signed-in direct users can inspect request metadata in the usage dashboard. Sanitized request bodies and up to 20 KB of response content are retained for 7 days. Secrets and personal fields are redacted before storage.