The public API supports retryable automation and consistent failure handling.
Error envelope
API errors return a stable error object with:
code, a stable error code.message, a human-readable explanation.request_id, when available.- Optional details for validation, auth, scope, or conflict failures.
Request ids
Log request ids from failed calls. Support may ask for them when investigating API, MCP, or webhook incidents.
Idempotency
Mutating REST requests require an Idempotency-Key header. Mutating MCP tool calls require arguments.idempotency_key. Reuse the same key when retrying the same logical operation. Do not reuse one key for different operations.
Rate limits
Public API responses include rate-limit headers. When a limit is exceeded, the API returns 429 with a retry hint. Mutating product actions also have owner and token quotas. Use exponential backoff for retries.
Safe retry pattern
- Generate one idempotency key for the intended operation.
- Send the request.
- If the network fails or a retryable response is returned, retry with the same key.
- Log the final request id and response.