Errors
How the merchant API reports problems, and what to show your buyers.
Errors use standard HTTP status codes. The body always has success: false and a human-readable message. Some errors add a machine-readable code and extra fields.
{
"success": false,
"message": "…",
"code": "SHIPPING_DETAILS_REQUIRED",
"missing": ["address.line1"]
}Status codes
| Status | When | Extra fields |
|---|---|---|
400 | Invalid request: a price sent on an item, a bad product ID, an unavailable product, invalid options, a bad paymentRail or expiresAt, an invalid embed origin | code on some errors |
400 SHIPPING_DETAILS_REQUIRED | A physical item without the buyer's name, email or address | code, missing |
401 | Missing, invalid or revoked key | |
403 | Key lacks the scope; or embed origin not registered | grantedScopes, effectiveScopes, hint |
403 ACCOUNT_FLAGGED | The account is restricted | code |
404 | Not found, or not yours. Swop answers 404 rather than 403 so IDs can't be probed. | |
429 | Too many requests | retryAfter (seconds) |
5xx | Something went wrong at Swop. Safe to retry reads; see the note below for creates. | correlationId when present |
Retrying
- Reads (
GET) are always safe to retry with backoff. POST /checkout-intentshas no idempotency key yet. If it times out, check whether you got anintentIdbefore retrying, or accept that you may create a second checkout (only the one the buyer pays matters).- On
429, waitretryAfterseconds.
What to show buyers
Key and scope errors (401, 403) mean your configuration is wrong, not the buyer's. Log the full body on your server and show the buyer something neutral, like "Checkout is temporarily unavailable". Never show a buyer "you weren't charged" unless you've confirmed the checkout's status is active, expired or cancelled.