Actions and retries
On 429, wait for Retry-After. After a timeout, check the order before repeating an action. Never automatically retry order creation: it has no idempotency key, so a second POST can create a duplicate.
Errors
Branch on code, not the human-readable error message.
{ "code": "amount_below_minimum", "error": "Amount is below the minimum.", "minAmountUsd": 20 }
code | Status | Next step |
|---|---|---|
invalid_request | 400 | Check the request; do not retry unchanged. See generic refusals. |
unauthorized | 401 | Check the credential and where it is sent. |
forbidden | 403 | Check the credential's permissions and forwarding approval. |
not_found | 404 | Check the order ID and access proof; either may be invalid. |
conflict | 409 | Refresh the order before another action. |
amount_below_minimum | 400 | Read minAmountUsd, increase the amount, and re-quote. |
no_route | 400 | Try another amount or quote again later. |
rate_limited | 429 | Wait for Retry-After / retryAfter, in seconds. |
unavailable | 503, 500, 504 | Retry reads and quotes with backoff; check state before repeating writes. |
request_failed | 400 | An upstream step failed; re-read the order before another action. |
Request and order quotas
Server partner keys share company limits. Public-client keys, first-party keys, and anonymous requests use IP limits. Read access from GET /v2/integrator/me for your current company limits.
Approved IP forwarding adds per-client limits within the company ceiling. Once enabled, requests without the header share one client allowance.
Creation consumes request and creation-attempt capacity; refusals can count too. Quotes and individual keys may have additional limits.
Identify the exhausted limit
X-RateLimit-Resource identifies a Core quota refusal. Upstream refusals may omit it.
| Value | Limit |
|---|---|
requests | Company or IP requests |
key_requests | Additional key request cap |
creation | Swap and bridge creation attempts |
quotes | Quotes |
open_orders | Unfinished orders |
client_requests | Client requests within the integration |
client_creation | Client creation attempts |
client_open_orders | Client unfinished orders |
All applicable limits must allow a request. Retry-After tells you when to check again; it does not reserve capacity.
Unfinished orders count within the configured creation window. Completed, failed, expired, refunded, and older orders stop counting. This is separate from the funding deadline, expiresAt. Rotating or revoking a key does not free existing slots.
Deliberately generic refusals
What does “Invalid request” mean?
A generic 400 invalid_request can mean invalid input or a policy refusal. The response does not distinguish them. Show a neutral failure message and do not retry unchanged. When a response names an invalid field, correct that field.
Actions
Owner actions require X-Session-ID. Read-only destination verification cannot authorize them. Show interactive controls only when customerState.kind is action_required, using its action value.
Action-specific rules
| Action | Behavior |
|---|---|
| Delete | Hides the order from session history; does not cancel it or reverse funds. |
| Coinflip | Requires action coinflip. Send explicit accept: true or false. Refresh on 409 or 504 before retrying. |
| Review | Once after completion: three integer ratings from 1–5, optional comment up to 500 characters. |
| Refund address | Requires action refund_address. Saves one immutable destination; does not itself send a refund. Use refundRecovery for wrong-chain details. |
Supporting resources provide form data. Their presence, the order status, and elapsed time do not authorize an action.
Retry policy
Retry reads and quotes with bounded backoff. After a WebSocket reconnect or an uncertain write response, re-read the order. A supplied sessionId groups ownership but does not deduplicate creation requests.