Rate limits

Predictable. Defendable. Documented in headers on every response.

The numbers

Resource	Per-key limit
Snapshot reads (`GET /partner/v1/users/:id/snapshot`)	100 requests per second, sustained
Snapshot read burst	Up to 200 RPS for 5 seconds
Consent link generation (`POST /partner/v1/consent-links`)	50 RPS sustained, 100 RPS burst
Disbursements (`POST /partner/v1/disbursements`)	30 RPS sustained, 60 RPS burst
Webhook subscription management	10 RPS sustained
Inbound webhook delivery to you	Unlimited (you’re receiving, not requesting)

These are per-API-key. Multiple keys for the same partner don’t multiply; we enforce limits per-key and aggregate them at the partner level (so creating 10 keys to bypass the limit doesn’t work). If you need more, talk to us. We provision dedicated capacity at a higher tier for high-volume integrations — typically banks running large origination workflows.

How rate-limit signaling works

Every response carries three headers:

Header	Meaning
`X-RateLimit-Limit`	The current limit for this resource (e.g., 100).
`X-RateLimit-Remaining`	How many requests you have left in the current window.
`X-RateLimit-Reset`	Unix timestamp when the bucket refills.

When you exceed the limit, we return 429 Too Many Requests:

HTTP/1.1 429 Too Many Requests
Retry-After: 3
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1755168156

{"error_code":"rate_limited","message":"Rate limit exceeded. Retry in 3 seconds.","requestId":"req_..."}

The Retry-After header tells you how long to wait before retrying.

Bucket algorithm

We use a token bucket per API key, refilled at the sustained rate. The bucket capacity is the burst limit.

Snapshot reads: bucket capacity 200, refill rate 100/sec → you can burst up to 200 in 5 seconds, then drop to 100/sec sustained.
Disbursements: bucket capacity 60, refill rate 30/sec → similar logic.

The bucket is per-key and shared across all our regions; no per-region pool.

What counts as a request

✅ Snapshot fetches.
✅ Consent link generation.
✅ Disbursement initiation.
✅ Webhook subscription management.
❌ Webhooks delivered to you (you’re not requesting; we are).
❌ Failed auth (401, 403) — these are still rate-limited but at a much lower per-key threshold (10/min) to prevent brute force.
❌ Idempotent retries against the same Idempotency-Key — only the first attempt counts.

Idempotency keys and retries

For write operations (disbursement, webhook subscription management), you can include an Idempotency-Key header. We dedupe on it for 24 hours. If you retry a request after a 5xx response, including the same Idempotency-Key, we recognise it as a retry and either complete the original request (if it succeeded behind the scenes) or fail-safe (returning the original error if it permanently failed). Idempotent retries don’t consume additional rate-limit tokens.

curl -X POST https://api.guild.com.ng/partner/v1/disbursements \
  -H "Authorization: Bearer gld_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"userId":"usr_...","amountKobo":"5000000","reason":"loan_disbursement"}'

Use a fresh UUID per logical request, the same UUID per retry of that request.

When you hit the limit

Three patterns. Pick what fits your architecture. Exponential backoff with jitter. The classic. On 429, wait Retry-After + random(0, 2) seconds, then retry.

import time, random, requests

def fetch_with_backoff(url, headers, max_attempts=5):
    for attempt in range(max_attempts):
        r = requests.get(url, headers=headers)
        if r.status_code != 429:
            return r
        retry_after = int(r.headers.get('Retry-After', 1))
        time.sleep(retry_after + random.random() * 2)
    raise Exception("Max retries exceeded")

Queue with a worker pool. Drop requests into a queue. Have N workers that respect the per-key limit. If you’re at 100 RPS sustained, run 100 workers each doing 1 RPS, or 10 doing 10 RPS. Schedule offline. For batch workloads (e.g., refreshing snapshots overnight for your active borrowers), schedule the work for off-peak hours. The limits are unchanged but you have less contention with your real-time origination traffic.

What if I need higher limits?

A few options.

Need	Solution
Periodic burst (end-of-month statement run, etc.)	Talk to us — we can grant a temporary higher burst for a specific time window.
Sustained higher throughput	Move to a dedicated capacity tier. Pricing is volume-based.
Multiple parallel teams using the same partner account	Use scoped keys (read:snapshots, write:disbursements) — each gets its own bucket.

Most production partner integrations operate well under 100 RPS on average — the limit is sized to handle peak underwriting load (e.g., 30-50 simultaneous loan applications in a busy hour). If you’re brushing it, that’s usually a sign your access patterns can be optimized (cache snapshots within their freshness window, batch consent generations).

Errors that look like rate limits but aren’t

Sometimes you’ll see 5xx errors from us during a normal-looking traffic pattern. A few common causes:

A OPay upstream call took >10 seconds. We retry on our side; the partner API surface waits up to 30s for the underlying operation before timing out.
A database read replica is rebalancing. A small window of elevated latency, sometimes a 5xx, never longer than a few seconds.
Our standing model is recomputing for the user. Snapshot reads against a user whose score is recomputing wait for the recompute. Usually under 100ms, occasionally up to 2s.

None of these count against your rate limit. They’re operational hiccups on our side, and we own them.

Monitoring your own usage

The Partner Portal dashboard shows your per-key request counts, success rate, and rate-limit hits over the last 24h, 7d, 30d. We surface a leading indicator at 80% utilisation: if you’re consistently using >80% of your sustained limit, we’ll send you a heads-up email suggesting you talk to us about higher capacity. You can also query usage via the API:

curl https://api.guild.com.ng/partner/v1/usage \
  -H "Authorization: Bearer gld_live_..."

Returns rolling counts per resource for the trailing hour, day, and month.

Overview

Back to the Partner hub.

API Reference

Complete REST reference for every Partner API endpoint.

Get Started

For Job Seekers

For Traders

For Employers

For Partners

Channels

Standing & the Ledger

Architecture

Security & Trust

The numbers

How rate-limit signaling works

Bucket algorithm

What counts as a request

Idempotency keys and retries

When you hit the limit

What if I need higher limits?

Errors that look like rate limits but aren’t

Monitoring your own usage

Next

Overview

API Reference

​The numbers

​How rate-limit signaling works

​Bucket algorithm

​What counts as a request

​Idempotency keys and retries

​When you hit the limit

​What if I need higher limits?

​Errors that look like rate limits but aren’t

​Monitoring your own usage

​Next

Overview

API Reference

The numbers

How rate-limit signaling works

Bucket algorithm

What counts as a request

Idempotency keys and retries

When you hit the limit

What if I need higher limits?

Errors that look like rate limits but aren’t

Monitoring your own usage

Next