# Errors (/docs/api-reference/errors)

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.

```json
{
  "success": false,
  "message": "…",
  "code": "SHIPPING_DETAILS_REQUIRED",
  "missing": ["address.line1"]
}
```

{/* TODO(review): error envelopes aren't uniform yet: some include `state`, some `status` and `correlationId`. Normalise before launch. */}

## Status codes [#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 [#retrying]

- **Reads** (`GET`) are always safe to retry with backoff.
- **`POST /checkout-intents`** has no idempotency key yet. If it times out, check whether you got an `intentId` before retrying, or accept that you may create a second checkout (only the one the buyer pays matters).
- On `429`, wait `retryAfter` seconds.

## What to show buyers [#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`.
