Preview documentation. The interface is being rolled out — examples are indicative, and we will confirm final values at launch.
Integration troubleshooting
This page collects common Commerce API integration issues and where to look for
the cause. Include correlation_id from the error response in every support
ticket — it identifies the specific request.
Rejected authentication (401)
Most common causes of invalid_signature:
Symptom (code) |
Cause | Fix |
|---|---|---|
expired_timestamp |
X-CBA-Timestamp outside the 300 s window |
synchronize server clock (NTP); send a fresh timestamp on each signature |
replay_nonce |
X-CBA-Nonce reused in the window |
generate a unique nonce per request |
invalid_signature |
wrong canonical string or secret | verify signature element order: method, path, query, timestamp, nonce, body hash |
Signature details: Authentication.
Idempotency conflicts (409)
idempotency_key_reused— sameIdempotency-Keywith different body. Use a new key for new content, or repeat identical body to get the stored response.stale_source_version— an older resource version was sent. Fetch current state and increasesource_version.
Full contract: Idempotency, replay, source version.
Missing permissions (403)
insufficient_scope means the key lacks the required scope (e.g.
orders:write). Check key scopes and create a key with the correct permission
set — see the table in Authentication.
Rejected data (422)
validation_failed returns a per-field error list (errors). Common cases:
missing required price/currency, phone not in E.164, missing consent proof, or
incomplete order line items. Fix the indicated fields — the request had no side
effect.
Limits and overload (413 / 429 / 503)
payload_too_large(413) — body exceeds 2 MiB or batch exceeds limits; split into smaller batches. See Limits.rate_limited(429) — too many requests; wait forRetry-Afterand retry.tenant_unavailable(503) — temporary unavailability; retry with backoff, not as a permanent failure.
Webhook not arriving
Outbound delivery diagnosis (endpoint down, HTTPS required, private address rejection, retries and replay) is described separately: Webhooks: signature, retry, replay and in the Help Center: Webhook not delivered.