Errors & retries
Use the HTTP status and response message to decide what to do next.
401 Unauthorized
Check that the key is valid, unexpired and belongs to an active connection.
403 Forbidden
The key lacks a required permission, or product moderation blocks this action.
404 Not found
Check the resource ID and the store that owns this connection.
409 Conflict
Read the error message. Reconcile stale versions or conflicting IDs before retrying a changed request with a new operation key.
422 Validation failed
Correct the fields named in errors.
429 Too many requests
Wait for Retry-After. The initial limit is 120 requests per minute per caller IP.
5xx Server error or timeout
The result may be unknown. Retry the identical body and path using the original Idempotency-Key.
Retry writes safely
Idempotency-Key: YOUR_UNIQUE_OPERATION_IDUse a new 8–120 character key for each operation. After a timeout, reuse the same key, path and body. A changed request needs a new key.
An identical successful retry returns the saved result with Idempotent-Replayed: true.