Errors and retries
Handle transport status before interpreting the response body. An HTML error page from a proxy is not a successful JSON API response. Avoid logging Authorization headers, full click tokens, personal metadata, or raw payment records.
HTTP status guide
| Status | Meaning | Recovery |
|---|---|---|
| 400 / 422 | Invalid fields, token, timestamp, or request shape | Correct the request; do not retry unchanged indefinitely |
| 401 | Missing, invalid, expired, or revoked credential | Check credential type and workspace; replace or reissue it |
| 402 | Plan allowance or feature limit | Review workspace usage and plan; retrying immediately will not fix it |
| 403 | Wrong permission, credential kind, or security requirement | Use the appropriate server key or owner-authorized MCP token |
| 404 | Missing, unavailable, or inaccessible resource | Check ID, domain, path, archive state, and workspace |
| 405 | Unsupported method | Use the documented verb; MCP is POST-only |
| 409 | Conflicting idempotency identity or state | Compare the original payload; do not overwrite the immutable event |
| 413 | Request too large | Reduce payload size; obey per-field bounds |
| 429 | Request throttled | Back off with jitter; honor Retry-After when provided |
| 5xx / network error | Transient failure or uncertain completion | Retry with the same identity and payload when the operation is idempotent |
Error body details can vary by validation layer. Use status as the stable control signal, show a helpful message, and retain a sanitized diagnostic record. MCP has an additional JSON-RPC and tool-error layer; see MCP tools.
Retry strategy
Use bounded exponential backoff with jitter. Limit concurrent requests and total retry time. Preserve the original event ID, link key, payload, and event timestamp across retries. A timeout can happen after the server commits the operation.
After the retry budget is exhausted, keep backend events in a durable outbox for later reconciliation. Record the response ID when delivered and make your worker safe to restart. Do not generate a replacement payment event ID to bypass 409.
Operations that create duplicates
POST /v1/shares, MCP create_publishable_key, register_mobile_app, and create_setup_link are not covered by event or link-key idempotency. If their response is lost, inspect workspace state before issuing another create.
SDK queues
JavaScript's client queue keeps at most 100 undelivered events. Network errors, 429, and 5xx can result in { queued: true }, which is not a delivery receipt. Consent denial can result in { skipped: true }. Read the SDK guide for flush behavior, stale attribution tokens, and storage lifetime; native SDK behavior is documented separately.
Browser and device storage can be cleared or unavailable. Report financial events from your backend with durable delivery, not from a mobile queue.
Ask for help
Send a sanitized timestamp, HTTP status, route, SDK/version, and reproducible steps to support@linkrunway.com. Never send a full API key, MCP token, session cookie, or webhook signing secret.