BlooBank API Documentation

Proposed defaults — pending product confirmation. The exact rate-limit values and header names below are aligned with industry conventions (AWS, GitHub, Stripe). Concrete numbers for the BlooBank Transactions Engine will be finalized before this page exits “Proposed” status.

The BlooBank API applies rate limits per credential to protect platform stability. This page documents how clients should interpret rate-limit responses and back off gracefully.

How limits are applied

Scope	What it counts
Per credential (Access Key)	All requests authenticated with the same `X-Access-Key`.
Per endpoint	Each endpoint has its own bucket. Hitting a limit on `POST /paymentOrders` does not throttle `GET /wallets`.
Sliding window	Limits are evaluated continuously, not in fixed wall-clock buckets.

Limits are applied after authentication. An unauthenticated burst will fail with SIGNATURE_INVALID long before it consumes quota.

When you exceed a limit

The API returns HTTP 429 with error.status: "RESOURCE_EXHAUSTED":

{
  "error": {
    "code": 429,
    "status": "RESOURCE_EXHAUSTED",
    "message": "Rate limit exceeded for this credential.",
    "details": [
      {
        "reason": "RATE_LIMIT_EXCEEDED",
        "description": "You have exceeded the request quota for this endpoint.",
        "metadata": {
          "limit": 100,
          "window_seconds": 60,
          "retry_after_seconds": 12
        }
      }
    ]
  }
}

The response also includes a Retry-After HTTP header carrying the same hint as metadata.retry_after_seconds.

Recommended response

Honor Retry-After when present

Use either the Retry-After header or details[0].metadata.retry_after_seconds. Wait at least that long before retrying.

Apply exponential backoff with jitter

For repeated RESOURCE_EXHAUSTED (or in absence of Retry-After), back off exponentially: min(2^attempt × base_delay, max_delay) and add full jitter.

Bound your retries

Three attempts is a reasonable default. After that, surface the failure to the caller — escalating without backoff would compound the throttling.

Keep `idempotencyKey` stable across retries

Throttled creates should retry with the same idempotencyKey so a partially-succeeded request is not duplicated. See Idempotency.

Backoff reference

A canonical exponential backoff with full jitter (AWS guidance):

function delayMs(attempt: number): number {
  const base = 500;       // 500ms
  const cap  = 30_000;    // 30s
  const exp  = Math.min(cap, base * 2 ** attempt);
  return Math.random() * exp; // full jitter: random in [0, exp)
}

let attempt = 0;
while (attempt < 3) {
  try {
    return await api.call(req);
  } catch (err) {
    if (err.status === 'RESOURCE_EXHAUSTED') {
      const hint = err.details?.[0]?.metadata?.retry_after_seconds;
      const wait = hint ? hint * 1000 : delayMs(attempt);
      await sleep(wait);
      attempt++;
      continue;
    }
    throw err;
  }
}

What does not count against quota

Failed authentication (SIGNATURE_INVALID, TIMESTAMP_SKEW_EXCEEDED, REPLAY_DETECTED). These are rejected at the edge and do not consume per-endpoint quota — but they do consume an authentication-attempt quota with its own (more permissive) limit.
Webhook acknowledgements (your 2xx response to a delivery). Webhooks are server→you; no quota applies on the return path.

Best practices

Pattern	Why
Concurrent worker cap	Hold concurrency at a level below the steady-state rate limit. Bursts above that level should queue, not fire.
Per-tenant fan-out	If you run multi-tenant infrastructure, spread your call cadence so one tenant’s burst does not block another’s normal traffic.
Cache wallet metadata	`getWallet` results change rarely. Cache them for minutes, not seconds.
Avoid hot loops	Polling `getPaymentOrder` in a tight loop is the most common reason integrators hit limits — use webhooks for state changes.

Increasing your limit

Per-credential limits are configurable for production workloads. To request an increase, contact your BlooBank account team with:

Your X-Access-Key (the credential needing the bump).
The endpoint(s) and target rate.
A brief description of the workload (steady vs. bursty, peak hours, etc.).

Retry strategy

Backoff for UNAVAILABLE and RESOURCE_EXHAUSTED in detail.

Webhooks

Reduce polling — receive state changes by push.

Introduction

Concepts

Authentication

Errors

Wallets

Payments

Rate limiting

How limits are applied

When you exceed a limit

Recommended response

Backoff reference

What does not count against quota

Best practices

Increasing your limit

Next

Retry strategy

Webhooks

​How limits are applied

​When you exceed a limit

​Recommended response

​Backoff reference

​What does not count against quota

​Best practices

​Increasing your limit

​Next

Retry strategy

Webhooks

How limits are applied

When you exceed a limit

Recommended response

Backoff reference

What does not count against quota

Best practices

Increasing your limit

Next