# Errors (/docs/get-started/errors)

Swop uses normal HTTP status codes. `2xx` worked, `4xx` means something in the request needs fixing, and `5xx` means something went wrong on Swop's side.

## The error body [#the-error-body]

Error responses have `success: false` and a human-readable `message`. Some include a machine-readable `code` and extra fields that help you fix the request.

```json
{
  "success": false,
  "state": "failed",
  "message": "This key does not have the \"commerce.checkout\" scope right now.",
  "grantedScopes": ["commerce.read"],
  "effectiveScopes": ["commerce.read"]
}
```

Write your code against `success` and the status code, and show `message` to people. Not every error has a `code` yet.

## Common errors [#common-errors]

| Status | When | Extra fields |
|---|---|---|
| `400` | A price was sent with an item. Swop prices items itself, so this is rejected, not ignored. | — |
| `400` `SHIPPING_DETAILS_REQUIRED` | A physical item without the buyer's name, email or address | `code`, `missing` (e.g. `["address.line1"]`) |
| `400` | Bad product ID, product unavailable, invalid options, bad `paymentRail` or `expiresAt` | — |
| `401` | Missing, invalid or revoked key | — |
| `403` | The key lacks the required scope | `grantedScopes`, `effectiveScopes`; `hint` for card |
| `403` `ACCOUNT_FLAGGED` | The account is restricted | `code` |
| `403` | The website asking for an embed token isn't registered | — |
| `404` | The product isn't yours, or the checkout doesn't exist | — |
| `429` | Too many requests | `retryAfter` (seconds) |

## Card isn't offered [#card-isnt-offered]

If you ask for card and get crypto only, your account isn't verified for card yet, or the cart doesn't qualify. Crypto checkout never needs verification.

{/* TODO(review): the API doesn't yet say *why* card wasn't offered (WS10 gap 8). Error envelopes are not fully uniform yet (gap 9). */}
