Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt

Use this file to discover all available pages before exploring further.

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

ScopeWhat it counts
Per credential (Access Key)All requests authenticated with the same X-Access-Key.
Per endpointEach endpoint has its own bucket. Hitting a limit on POST /paymentOrders does not throttle GET /wallets.
Sliding windowLimits 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.
1

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.
2

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.
3

Bound your retries

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

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

PatternWhy
Concurrent worker capHold concurrency at a level below the steady-state rate limit. Bursts above that level should queue, not fire.
Per-tenant fan-outIf you run multi-tenant infrastructure, spread your call cadence so one tenant’s burst does not block another’s normal traffic.
Cache wallet metadatagetWallet results change rarely. Cache them for minutes, not seconds.
Avoid hot loopsPolling 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:
  1. Your X-Access-Key (the credential needing the bump).
  2. The endpoint(s) and target rate.
  3. A brief description of the workload (steady vs. bursty, peak hours, etc.).

​
Next

Retry strategy

Backoff for UNAVAILABLE and RESOURCE_EXHAUSTED in detail.

Webhooks

Reduce polling — receive state changes by push.