# Errors

> Error envelope and codes.

## Envelope

All error responses share the same JSON shape:

```json
{
	"ok": false,
	"error": {
		"code": "rate_limited",
		"message": "Rate limit exceeded. Maximum 60 requests per minute."
	}
}
```

## Codes

| HTTP | Code | When |
| ---- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `invalid_json` | Request body was not valid JSON. |
| 400 | `invalid_request` | JSON parsed but failed schema validation. Carries `issues`. |
| 400 | (none) | No upstream status to report: the URL did not resolve to a supported provider, or the call never reached the bank. Read `error`. |
| 401 | `missing_key` | No `x-api-key` header. |
| 401 | `invalid_key` | Key not recognised. |
| 401 | `revoked_key` | Key was revoked. |
| 429 | `rate_limited` | Hit the per-minute request rate. Includes `Retry-After`. |
| 429 | `quota_exceeded` | Hit the plan's uncached verification cap. Carries `used` and `cap`, plus `Retry-After` to the window rollover. |
| 429 | `image_cap_reached` | Hit the plan's monthly screenshot read allowance. `POST /api/verify-image` only. |
| 429 | `ocr_daily_cap_reached` | The service-wide daily screenshot budget is spent. Rare, and not about your account. |
| 502 | (none) | The bank answered but the receipt failed validation. See `error` and the partial `receipt`. |

There is **no 504**. A call that times out or gives up waiting for a busy bank
has no upstream status code to report, so it comes back as a 400 with the
reason in `error`. See
[what a busy bank does](/docs/integration-flows#what-a-busy-bank-does-to-a-sync-call).

`POST /api/verify-image` can also return `ai_not_configured` (503, the
extractor is not set up on this deployment) and `detection_failed` (502, the
extractor ran but could not read a receipt reference out of the image).

## When a bank is down

We always ask the bank, even when our health checks say it is failing. Some
banks drop a share of requests and answer the rest, so asking gets some
through where refusing would get none. A bank that is down for real comes back
as the busy-bank **400** or a **502**. [`GET /api/status`](/docs/health) shows
what our health checks see per component.

## Retry guidance

- **`rate_limited`** wait the `Retry-After` interval, then try again.
- **`quota_exceeded`** and **`image_cap_reached`** do not retry on a timer.
 `Retry-After` can be days away, because the window is your plan's, not a
 minute. Upgrade, enable overage, or wait for the rollover.
- **502** and the busy-bank **400** are usually the bank rather than you.
 Retry after 1 to 2 s with jitter and treat three consecutive failures as a
 real outage. Do not retry a Siinqee reference at all: those links allow about
 five views in total, so a retry loop destroys the receipt. See
 [providers](/docs/providers).
- **401** never retry. Mint a new key from the dashboard.
- **400 `invalid_request`** never retry. The body is wrong.
