BlooBank API Documentation

This page is the how-to complement to the Errors overview. It shows the branching pattern in concrete code and the retry rules per error class.

The branching pattern

The canonical branching pattern in pseudocode:

response = http_call(request)

if response.status_code < 400:
  return response.body                            // success

err = response.body.error
switch err.status:
  case "INVALID_ARGUMENT":
    surface_validation_errors(err.details)        // user-facing; do not retry
    return give_up

  case "IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS":
    // The key was bound to a different body — pick a new key
    return give_up_or_reconcile

  case "RESOURCE_EXHAUSTED":
    return retry_with_backoff(request, max_attempts=3)

  case "PROVIDER_UNAVAILABLE", "DATABASE_UNAVAILABLE", "UPSTREAM_UNAVAILABLE":
    return retry_with_backoff(request, max_attempts=3)

  case "SIGNATURE_INVALID", "TIMESTAMP_SKEW_EXCEEDED":
    // Fix the root cause (clock, low-S, body bytes) before any retry
    return give_up

  case "REPLAY_DETECTED":
    // Generate a fresh X-Access-Request-Id and re-sign
    return retry_with_fresh_request_id(request, once=true)

  case "WALLET_NOT_FOUND", "PAYMENT_ORDER_NOT_FOUND":
    return give_up                                // not going to appear later

  case "RBAC_DENY":
    log_decision_id(err.details[0].metadata.decisionId)
    return give_up

  case "INTERNAL":
    log_record_id(find_metadata_id(err.details, reason="ERROR_RECORDED"))
    return give_up                                // do not retry blindly

  default:
    return give_up

Two rules of thumb:

Never branch on error.message — it is unstable.
Always inspect error.details[] before treating an error as terminal — the specific reason often dictates a different recovery path.

Concrete examples

async function createPaymentOrder(client, wallet, body, attempt = 0) {
  try {
    return await client.request('POST', `/wallets/${wallet}/paymentOrders`, body);
  } catch (err) {
    const e = err.body?.error;
    if (!e) throw err;

    switch (e.status) {
      case 'INVALID_ARGUMENT':
        for (const d of e.details) {
          console.error(`Invalid field "${d.metadata?.field}": ${d.description}`);
        }
        throw err;

      case 'IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS':
        console.error('Idempotency key already used with different body');
        throw err;

      case 'RESOURCE_EXHAUSTED':
      case 'PROVIDER_UNAVAILABLE':
      case 'DATABASE_UNAVAILABLE':
      case 'UPSTREAM_UNAVAILABLE':
        if (attempt >= 3) throw err;
        await sleep(backoffMs(attempt));
        // KEEP the same idempotencyKey; mint a fresh requestId in the signer
        return createPaymentOrder(client, wallet, body, attempt + 1);

      case 'INTERNAL':
        const recordId = e.details.find(d => d.reason === 'ERROR_RECORDED')?.metadata?.id;
        console.error(`Internal error — reference id ${recordId}`);
        throw err;

      default:
        throw err;
    }
  }
}

function backoffMs(attempt) {
  const base = 500, cap = 30_000;
  return Math.random() * Math.min(cap, base * 2 ** attempt);   // full jitter
}
const sleep = ms => new Promise(r => setTimeout(r, ms));

import time, random
from requests.exceptions import HTTPError

def create_payment_order(client, wallet, body, attempt=0):
    try:
        return client.create_payment_order(wallet, body)
    except HTTPError as exc:
        e = exc.response.json().get('error', {})
        status = e.get('status')

        if status == 'INVALID_ARGUMENT':
            for d in e.get('details', []):
                field = d.get('metadata', {}).get('field')
                print(f'Invalid field "{field}": {d.get("description")}')
            raise

        if status == 'IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS':
            print('Idempotency key already used with different body')
            raise

        if status in {'RESOURCE_EXHAUSTED', 'PROVIDER_UNAVAILABLE',
                      'DATABASE_UNAVAILABLE', 'UPSTREAM_UNAVAILABLE'}:
            if attempt >= 3:
                raise
            time.sleep(backoff_seconds(attempt))
            return create_payment_order(client, wallet, body, attempt + 1)

        if status == 'INTERNAL':
            record_id = next((d['metadata'].get('id') for d in e.get('details', [])
                              if d.get('reason') == 'ERROR_RECORDED'), None)
            print(f'Internal error — reference id {record_id}')
            raise

        raise

def backoff_seconds(attempt: int) -> float:
    base, cap = 0.5, 30.0
    return random.uniform(0, min(cap, base * (2 ** attempt)))    # full jitter

Retry semantics by status

Apply this table without modification — it is the standard.

`error.status`	Retry?	How
`INVALID_ARGUMENT`	No	The request is malformed. Fix it.
`IDEMPOTENCY_KEY_IN_USE_WITH_DIFFERENT_PARAMS`	No	The key is burned for that wallet. Pick a new key.
`SIGNATURE_INVALID`	No	Fix signing (see Troubleshooting).
`TIMESTAMP_SKEW_EXCEEDED`	No (until clock fixed)	Sync NTP, then retry.
`REPLAY_DETECTED`	Yes, once	Generate a fresh `X-Access-Request-Id`.
`MISSING_HEADER`, `TIMESTAMP_INVALID`	No	Fix the headers.
`CREDENTIAL_DISABLED` / `REVOKED` / `EXPIRED`	No	Contact account team.
`RBAC_DENY`	No	Request role binding; capture `decisionId`.
`WALLET_NOT_FOUND`, `PAYMENT_ORDER_NOT_FOUND`	No	Not going to appear later.
`WALLET_ALREADY_EXISTS`	No	Reconcile with the existing wallet.
`LABEL_IMMUTABLE`	No	Names cannot be changed.
`PAYMENT_ORDER_NOT_AWAITING_APPROVAL`	No	Verify state via `GET` before retrying.
`PAYMENT_ORDER_INVALID_STATE`	No	Verify state via `GET` before retrying.
`RESOURCE_EXHAUSTED`	Yes, with backoff	Honor `Retry-After` if present; exponential backoff with jitter otherwise.
`PROVIDER_UNAVAILABLE`, `DATABASE_UNAVAILABLE`, `UPSTREAM_UNAVAILABLE`	Yes, with backoff	Transient infrastructure failure.
`INTERNAL`	No (by default)	Log `ERROR_RECORDED` id; escalate. Retry only if you have explicit reason to believe it was transient.

Detailed retry mechanics in Retry strategy.

Idempotency on retry

When you do retry — RESOURCE_EXHAUSTED, provider/database/upstream UNAVAILABLE, or the one-shot retry after REPLAY_DETECTED — keep these stable across attempts:

Field	Reuse on retry?	Why
`idempotencyKey` (in body)	✅ Yes	So a partial success is not duplicated.
Request body bytes	✅ Yes	Same hash → same signature input.
`X-Access-Key`	✅ Yes	Same credential.
`X-Access-Timestamp`	❌ No — read fresh	Stale timestamps fail clock-skew.
`X-Access-Request-Id`	❌ No — mint fresh	Stale ids fail `REPLAY_DETECTED`.
`X-Access-Signature`	❌ No — recompute	Timestamp and request-id change → signature changes.

The signer should be designed so that only the body bytes feed into the canonical request as content; everything else is fresh per attempt.

Logging recommendations

For every non-2xx response, log at minimum:

HTTP method and URL (without secret query-string values).
error.status and error.code.
Every details[].reason.
metadata.decisionId if present.
metadata.id from ERROR_RECORDED if present.
The full details[] array as structured JSON (designed to be safe to log).
Approximate UTC time of the request.
Your X-Access-Request-Id (your correlation handle).

Do not log: credentials, the private key, raw signatures, full request bodies containing PII.

Retry strategy

The exact backoff formula and limits.

Error catalog

Every reason code with HTTP status and remediation.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Handling errors

The branching pattern

Concrete examples

Retry semantics by status

Idempotency on retry

Logging recommendations

Next

Retry strategy

Error catalog

​The branching pattern

​Concrete examples

​Retry semantics by status

​Idempotency on retry

​Logging recommendations

​Next

Retry strategy

Error catalog

The branching pattern

Concrete examples

Retry semantics by status

Idempotency on retry

Logging recommendations

Next