BlooBank API Documentation

This is the authoritative reference for error.status (and error.details[].reason) values returned by the BlooBank Transactions Engine API. Branch on these in your client code; they are stable and additive. For the envelope structure, see Errors overview. For the full normative contract, see the Errors reference.

Authentication (HTTP 400/401)

These fire before any business logic runs — fix the request signing.

Reason	HTTP	What it means	What to do
`MISSING_HEADER`	400	One of the four required headers is absent.	Send all four `X-Access-*` headers.
`TIMESTAMP_INVALID`	400	`X-Access-Timestamp` is not a decimal integer in milliseconds.	Send Unix time in milliseconds (UTC).
`TIMESTAMP_SKEW_EXCEEDED`	401	Header timestamp is more than ±10 seconds from server time.	Sync your host clock via NTP.
`SIGNATURE_INVALID`	401	Signature does not verify against the canonical request.	See Troubleshooting.
`REPLAY_DETECTED`	401	This `(accessKey, requestId)` tuple was used within the last hour.	Generate a fresh `X-Access-Request-Id`.
`CREDENTIAL_DISABLED`	401	Your Access Key is currently disabled.	Contact BlooBank account team.
`CREDENTIAL_REVOKED`	401	Your Access Key was permanently revoked.	Request a new credential.
`CREDENTIAL_EXPIRED`	401	Your Access Key passed its expiry date.	Rotate the credential.

Authorization (HTTP 403)

The credential is valid but lacks permission for this action on this resource.

Reason	HTTP	What it means	What to do
`RBAC_DENY`	403	The credential lacks a required role binding.	Request appropriate role from BlooBank. Include `decisionId` from `metadata.decisionId`.
`WORKSPACE_DISABLED`	403	The workspace you are calling into is disabled.	Contact BlooBank account team.
`SERVICE_ACCOUNT_DISABLED`	403	The service account behind your credential is disabled.	Contact BlooBank account team.

Validation (HTTP 400)

The request payload, query, or path violates input constraints.

Reason	HTTP	What it means	What to do
`INVALID_ARGUMENT`	400	Generic class for request validation failures. Inspect `details[]` for specifics.	Fix the request.
`INVALID_FIELD` (in `details[].reason`)	—	A specific field in the JSON body failed validation. `metadata.field` names it.	Fix the named field.
`INVALID_ID`	400	An ID string is malformed and cannot be decoded.	Use a well-formed `id` (e.g., `wal_…`, `ord_…`).
`INVALID_FILTER`	400	The `filter` query parameter violates SFS-1 syntax or the endpoint schema.	See Filtering.
`INVALID_ORDER_BY`	400	The `order_by` parameter references an unknown field or invalid direction.	See Pagination reference.
`INVALID_PAGE_SIZE`	400	The `page_size` is outside the accepted range.	Use a value between `1` and `100`.
`INVALID_PAGE_TOKEN`	400	The `page_token` is malformed, expired, or context-mismatched.	Restart pagination from the beginning.
`UNSUPPORTED_FILTER_OPERATION`	400	The filter uses an operator not allowed on the field’s type.	Use `=` / `!=` for strings/booleans/enums; comparison operators only for numbers/timestamps.

Resource state (HTTP 404 / 409 / 422)

The request is well-formed but conflicts with the state of the target resource.

Reason	HTTP	What it means	What to do
`WALLET_NOT_FOUND`	404	The named wallet does not exist or you cannot see it.	Verify wallet name; check RBAC.
`PAYMENT_ORDER_NOT_FOUND`	404	The named payment order does not exist within the wallet.	Verify the `paymentOrder` id and wallet pairing.
`WALLET_ALREADY_EXISTS`	409	A wallet with the requested name already exists.	Pick a different name; names are immutable and globally unique.
`LABEL_IMMUTABLE`	422	Attempt to change a name that is immutable after creation.	Names cannot be changed — create a new resource if needed.
`IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS`	422	The `(wallet, idempotencyKey)` tuple was used with a different body.	Use a new `idempotencyKey`; the first body bound to that key is final.
`PAYMENT_ORDER_NOT_AWAITING_APPROVAL`	422	`PUT .../approve` on an order not in `AWAITING_APPROVAL`.	Verify the order’s current status before approving.
`PAYMENT_ORDER_INVALID_STATE`	422	`PUT .../cancel` on an order not in `AWAITING_APPROVAL`.	Verify the order’s current status before canceling.

Rate limiting (HTTP 429)

Reason	HTTP	What it means	What to do
`RESOURCE_EXHAUSTED`	429	Per-credential or per-endpoint rate limit exhausted.	Backoff with `Retry-After`; see Rate limiting.
`RATE_LIMIT_EXCEEDED` (in `details[].reason`)	—	Detail variant of `RESOURCE_EXHAUSTED`.	Same — use `metadata.retry_after_seconds`.

Server errors (HTTP 500 / 503)

Reason	HTTP	What it means	What to do
`INTERNAL`	500	Sanitized internal failure. `details[0]` is `ERROR_RECORDED` with `metadata.id`.	Log `metadata.id`; forward to support. Do not retry blindly.
`ERROR_RECORDED` (in `details[].reason`)	—	The server persisted an audit record. `metadata.id` (format `exc_…`) is the reference.	Forward `metadata.id` to support.
`PROVIDER_UNAVAILABLE`	503	Downstream payment provider is unavailable or returned a transient error.	Retry with exponential backoff.
`DATABASE_UNAVAILABLE`	503	Internal database unreachable.	Retry with exponential backoff.
`UPSTREAM_UNAVAILABLE`	503	Some upstream dependency is unreachable.	Retry with exponential backoff.
`PERSISTENCE_FAILURE`	500	Unexpected persistence-layer failure. Sanitized.	Forward `ERROR_RECORDED` id to support.

Authentication detail reasons

Some details[].reason codes are only meaningful inside the details[] array (not as a top-level error.status).

Reason	Where	What it means
`AUTHENTICATION_REQUIRED`	inside 401	No credentials were provided.
`AUTHENTICATION_INVALID`	inside 401	Credentials were provided but did not verify.
`TOKEN_EXPIRED`	inside 401	The session token has expired. Refresh and retry.

How this catalog evolves

Reasons are additive: new ones may appear; existing ones do not change meaning.
Domain reasons follow the {AGGREGATE}_{CONDITION} convention (e.g., WALLET_NOT_FOUND, PAYMENT_ORDER_INVALID_STATE).
Cross-cutting reasons follow {CONDITION} (e.g., INVALID_FIELD, INTERNAL, RESOURCE_EXHAUSTED).
Treat any reason not in this catalog as opaque — fall back to handling by error.status alone.

Handling errors

Branching patterns in code.

Retry strategy

When to retry and how.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Error catalog

Authentication (HTTP 400/401)

Authorization (HTTP 403)

Validation (HTTP 400)

Resource state (HTTP 404 / 409 / 422)

Rate limiting (HTTP 429)

Server errors (HTTP 500 / 503)

Authentication detail reasons

How this catalog evolves

Next

Handling errors

Retry strategy

​Authentication (HTTP 400/401)

​Authorization (HTTP 403)

​Validation (HTTP 400)

​Resource state (HTTP 404 / 409 / 422)

​Rate limiting (HTTP 429)

​Server errors (HTTP 500 / 503)

​Authentication detail reasons

​How this catalog evolves

​Next

Handling errors

Retry strategy

Authentication (HTTP 400/401)

Authorization (HTTP 403)

Validation (HTTP 400)

Resource state (HTTP 404 / 409 / 422)

Rate limiting (HTTP 429)

Server errors (HTTP 500 / 503)

Authentication detail reasons

How this catalog evolves

Next