# Errors

RFC 9457 problem details and how to handle them.

Errors are RFC 9457 `application/problem+json`:

```json
{
  "type": "https://api.banking.wirebloom.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_error",
  "detail": "1 field is invalid.",
  "requestId": "req_01J8Z6Q7R2",
  "errors": [
    {
      "field": "/amount/amountMinor",
      "code": "too_small",
      "message": "Amount must be greater than zero."
    }
  ]
}
```

- Branch on `code` (stable, snake_case; the last segment of `type`). Every code is listed in the [error catalogue](/errors) with its status and whether a retry can succeed.
- `errors[].field` is a JSON Pointer into the body (or `query.<name>` / `header.<name>`).
- Quote `requestId` (also the `X-Request-Id` response header) to support.

Common codes for integrators: `invalid_api_key` (401), `insufficient_scope`, `ip_not_allowed`, `tenant_forbidden` (403), `not_found` (404), `insufficient_funds`, `idempotency_key_in_use` (409), `precondition_failed` (412, stale `If-Match`), `validation_error`, `idempotency_key_reused`, `limit_exceeded` (422), `rate_limited` (429), `provider_error` / `provider_timeout` (502/504).

## Retrying

Retry only what can succeed later: `409 idempotency-key-in-use`, `429 rate-limited` (after `Retry-After`) and `5xx` with the same `Idempotency-Key`. Other `4xx` need a change on your side first.