Errors

Errors are RFC 9457 application/problem+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 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.