Rate limits & errors

This page explains how the API reports errors and how throttling works. For per-endpoint responses, see the API Reference.

Common response codes

Status	Description	Common causes
200 OK	Request successful	—
201 Created	Resource created	POST requests
400 Bad Request	Invalid request format or parameters	Missing fields, invalid JSON, validation errors
401 Unauthorized	Authentication failed	Missing/expired/invalid access token
403 Forbidden	Insufficient permissions	Missing required scope, client revoked
404 Not Found	Resource not found	Invalid ID, resource deleted
429 Too Many Requests	Rate limit exceeded	Too many requests in a short period
500 Internal Server Error	Server-side error	Contact support with the request ID
503 Service Unavailable	Temporarily unavailable	Retry with exponential backoff

Error response format

Every error response is a JSON object with a human-readable message. There is never a data array on an error response — data present means success.

Beyond message, the extra fields vary by endpoint and error type:

• Most catalog-endpoint 400s add a machine-readable error code and a requestId (e.g. INVALID_SORT_FIELD, INVALID_SYNC_TOKEN, SEARCH_TERM_TOO_LONG). GET /brands/search puts its code under code (with a details object) instead of error.
• The OAuth client-management endpoints return an errors array describing each invalid field on validation failures.
• Generic unhandled errors (500) return message plus a requestId — quote the requestId when contacting support.

Branch on the HTTP status code, and treat error/code/details/errors as optional extras rather than a guaranteed envelope.

Example (400 Bad Request, with an error code)

{
  "error": "VALIDATION_ERROR",
  "message": "Product code is required",
  "details": { "field": "productCode", "reason": "missing_required_field" }
}

Rate limiting

Two independent limits apply, and either can return 429 Too Many Requests:

• API Gateway throttling — 50 requests per second sustained, 100 burst. These are per-stage limits, not per-client: all M2M clients share the same pool.
• WAF per-IP rule — a single source IP is blocked after roughly 1,000 requests in any rolling 5-minute window, independent of the gateway throttle, and stays blocked until the window clears. This is the limit to design a full catalog seed around — a flat-out full pull will trip it. Page with size=100 and keep one IP under ~1,000 requests per 5 minutes (roughly 3/sec, sequential rather than parallel workers).

When rate limited, back off and retry with exponential backoff (see Best practices).