Errors, retries and rate limits

The Channel API and the Store API refuse requests in different shapes, and the gateway in front of both has a third. This page puts them side by side and says which refusals a client retries.

Three error shapes

A Channel API refusal:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": [
      { "path": "items[0].quantity", "code": "minimum", "message": "must be >= 1" }
    ],
    "requestId": "2f408915-2608-4f0e-90a7-2a7abd34f487"
  }
}

A Store API refusal:

{
  "code": "CONFLICT",
  "message": "Your cart changed. Review the current cart.",
  "fieldErrors": {}
}

• Channel API details names each field at fault as { path, code, message }; requestId equals the X-Request-Id response header.
• Store API message is written for the buyer and can be shown as is; fieldErrors is keyed by field on sign-up and password change.
• Branch on the code, never on the message text.

Codes side by side

Full lists: Channel API errors and Store API errors.

What to retry

Idempotency

Channel API. Every POST, PUT, PATCH and DELETE takes an Idempotency-Key header: 7 to 50 characters that name the request on your side (an order number, a webhook delivery id).

Keys are scoped per tenant and per endpoint, and a failed request is not stored. Beyond the 24 hours, onDuplicate: update (the default on creates) makes a replayed document an update by externalId, so a full feed can be sent again safely.

Store API. Checkout, cart.addMany, cart claims, invoice payments, saved payment methods, subscriptions and applications take idempotencyKey (or requestId) in the body: 7 to 50 characters from A-Z a-z 0-9 _ -. A retry with the same key answers the first attempt. A lost checkout.start answer is found again with checkout.status { idempotencyKey, quoteFingerprint }.

Kentro Pixel. Events are deduplicated on event_id per property for at least 14 days; server requests may add X-Kentro-Idempotency-Key (up to 128 characters). See Pixel server API.

Rate limits

Channel API

• Per tenant and per minute: 1,200 writes (POST, PUT, PATCH, DELETE) and 6,000 reads (GET) by default. Kentro sets higher limits per tenant.
• Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the window resets). A refusal is 429 rate_limited with Retry-After.
• POST /v1/batch counts every operation it carries.
• Bulk sizes: POST /v1/orders/import and POST /v1/products/import take up to 1,000 documents (answered 202, then GET /v1/operations/:id); POST /v1/batch takes up to 100 operations; POST /v1/fulfillment-queue/ship up to 100 entries; POST /v1/inventory/history up to 500 entries.

Store API

• catalog.suggest (the search typeahead): 30 requests per 3 seconds per buyer, per guest, or per X-Storefront-Client-Ip for signed-out visitors.
• application.start: 60 per minute; other application.* operations: 120 per minute.
• session.signup and account.confirm, buyer sign-in and password reset are limited per account and per source address. Send X-Storefront-Client-Ip so the limits key on the buyer, not on the storefront server.
• The gateway applies per-key limits as well. Bodies are limited to 64 KB, application uploads excepted.

Kentro Pixel

• 600 events per minute per public key (bursts up to 1,200) and 6,000 per server key (bursts up to 12,000); 100 events per browser request, 500 per server request. See Limits, errors and troubleshooting.

Staying under the limits

• Read X-RateLimit-Remaining and slow down before it reaches zero.
• Load history through the import endpoints, not one write at a time.
• Poll with updatedSince and a sensible interval instead of re-reading whole lists.
• Queue writes behind a single worker per tenant, so a burst from the source system becomes a steady stream.