Error codes and retry guidance

Structure of an error response

{
  "error": {
    "code": "invalid_parameter",
    "message": "store_id is required",
    "param": "store_id",
    "request_id": "req_01HV6N..."
  }
}

request_id is required when contacting support. Always include it in your error logs.

HTTP status codes

Main error codes

Retry guidance

Conditions safe to retry

• HTTP status is 429 or 5xx
• Network timeout / connection error
• For POST, always set an Idempotency-Key (to prevent duplicate creation)

Retry interval (exponential backoff + jitter)

function retryDelay(attempt) {
  // 1, 2, 4, 8, 16 seconds (max 32)
  const base = Math.min(Math.pow(2, attempt), 32);
  // ±25% jitter to avoid a thundering herd
  const jitter = base * (Math.random() * 0.5 - 0.25);
  return (base + jitter) * 1000;
}

Maximum retry counts

• Regular API: up to 5 times
• Batch processing: up to 10 times
• Triggered by user action: up to 2 times (don't keep them waiting)

For 429, prioritize the Retry-After header

HTTP/1.1 429 Too Many Requests
Retry-After: 30

→ Wait 30 seconds, then retry

Cases you must not retry

• 4xx (except 429): there is a problem with the request itself, so retrying gives the same result
• POST/PUT without an Idempotency-Key: risk of duplicate creation

Related guides

• The basics of requests and responses
• Rate limiting and throttling
• Back to the developer help index