# Errors and retries

Application errors normally use the following envelope. Rate-limit responses can omit `request_id`; include it when available in support requests:

```json
{
  "error": {
    "code": "no_active_xpub",
    "message": "Store has no active xpub for this environment...",
    "request_id": "b9fc7e29-587f-4dda-b220-86d7144893fe"
  }
}
```

Include the `request_id` when contacting support. It correlates to our server logs.

## Errors `POST /v1/invoices` can return

**401 authentication**

| Code              | When                                                                                                                        |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `api_key_invalid` | Missing `Authorization` header, malformed, or the key does not exist. Use `Authorization: Bearer sl_live_…` or `sl_test_…`. |
| `api_key_revoked` | Key was revoked from the dashboard or by an admin. Mint a new one.                                                          |

**403 authenticated but blocked**

| Code                     | When                                                                        |
| ------------------------ | --------------------------------------------------------------------------- |
| `auth_account_suspended` | Vendor account suspended by an admin. No invoice creation until reinstated. |

**402 payment required (billing lock)**

| Code              | When                                                                                                                                                                        |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `billing_overdue` | Live invoicing restricted by account billing. Check `/billing` for the applicable unpaid bill or account restriction. Only legacy Trial installations use trial exhaustion. |

**404 resource missing**

| Code                  | When                                                                                |
| --------------------- | ----------------------------------------------------------------------------------- |
| `not_found` (`Store`) | The store the API key belongs to was archived. Restore it or use a different store. |

**409 conflict / not configured**

| Code                           | When                                                                                                                                                                       | Resolution                                                                    |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `no_active_xpub`               | Store has no active xpub for this environment. Live invoices need a mainnet xpub; wallet-free Sandbox needs no xpub; legacy Test uses its existing receiving-wallet rules. | Add an xpub at `app.satlane.com/stores/<id>/xpubs`.                           |
| `gap_limit_exceeded`           | Wallet's gap limit is within 5 of being reached and we have not seen recent funding.                                                                                       | Bump the gap limit in Electrum (recommend 100+) or rotate xpubs.              |
| `sandbox_contract_unavailable` | Versioned Sandbox requested on an installation with rollout disabled.                                                                                                      | Confirm the installation mode; do not invent a payable fallback.              |
| `store_live_not_active`        | New Live creation requested before activation or while paused.                                                                                                             | Review the wallet and explicitly activate or reactivate the store.            |
| `idempotency_conflict`         | The same `Idempotency-Key` was reused with a **different request body**.                                                                                                   | Reuse the key with the original body (cached response) or generate a new key. |

**426 contract required**

Enabled Test invoice creation without the version header returns `sandbox_contract_required`. Send `SatLane-Version: 2026-10-05` after confirming this installation enables the contract.

**400 validation**

| Code                           | Cause                                                                                                                                                                                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation_error`             | Zod rejected the body. Common: missing both `(amount + currency)` and `amount_sats`, providing both, `expires_in_minutes` outside `[5, 120]`, invalid `callback_url`, `metadata` value > 255 chars. The `message` names the field. |
| `validation_error`             | `Idempotency-Key` header > 255 chars or empty.                                                                                                                                                                                     |
| `unsupported_contract_version` | The SatLane-Version header does not name the supported contract version.                                                                                                                                                           |
| `invalid_currency`             | Currency code not supported (only `USD` today).                                                                                                                                                                                    |
| `invalid_amount`               | Sats amount ≤ 0, or fiat amount rounds to zero sats at the current rate.                                                                                                                                                           |

**429 rate limited**

| Code           | When                                                                                      | Resolution                            |
| -------------- | ----------------------------------------------------------------------------------------- | ------------------------------------- |
| `rate_limited` | Invoice-route limit or enabled Sandbox hourly/daily/global/active-invoice budget reached. | Back off using `retry_after_seconds`. |

**503 temporary infrastructure (retry safe)**

These indicate a temporary infrastructure condition. Retry with backoff using the same idempotency key and body; they do not guarantee that every other validation will pass.

| Code                   | When                                                                                   |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `chain_syncing`        | Bitcoin node is in initial block download. We refuse new invoices against a stale tip. |
| `disk_full`            | Host critically low on disk. Writes blocked to protect webhook delivery state.         |
| `database_unavailable` | Postgres unreachable. Rare.                                                            |

## Recommended client retry policy

A connection timeout can leave the outcome uncertain. Keep the same idempotency key and request body, reconcile the order, and retry sequentially. Never create a fresh payment request merely because the first response was lost.

| HTTP                         | Action                                                                                 |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| 200 / 201                    | Use the response.                                                                      |
| 400, 401, 402, 403, 404, 409 | Stop. Caller bugs, billing lock, or configuration errors. Log and surface to the user. |
| 429                          | Back off using `retry_after_seconds`, then retry.                                      |
| 503                          | Exponential backoff (1s → 2s → 4s → 8s → 16s, max 5 tries).                            |
| Other 5xx                    | Treat as a bug on our side. Log `request_id`, escalate.                                |

**Always send an `Idempotency-Key`** when retrying creates. Successful responses are saved for sequential replay for 24 hours per key. Use globally unique keys and reconcile uncertain outcomes before starting a new create.

## Errors from other endpoints

A non-exhaustive selection:

- `auth_required` (401): session cookie missing on dashboard endpoints
- `auth_totp_required` (401): 2FA-gated endpoint; prompt for code and call `/v1/auth/totp/verify`
- `auth_email_not_verified` (403): vendor email not yet verified
- `invoice_not_cancellable` (409): invoice already paid / late_paid / cancelled / expired
- `invoice_expired` (410): payment flow hit a fully-expired invoice
- `invoice_already_paid` (409): duplicate paid transition attempt
- `not_found`: UUID does not match anything you own
- `gone` (410): resource intentionally removed