Errors

Every error response shares the same shape.

{
  "ok": false,
  "code": "consent_revoked",
  "message": "The consent for this user has been revoked.",
  "requestId": "req_01HMFB7ZQK..."
}

Field	Meaning
`ok`	Always `false` on errors. (`true` on success responses.)
`code`	Machine-readable error code. Stable across versions.
`message`	Human-readable description. May change for clarity; do not parse.
`requestId`	ULID for support correlation. Include in any ticket.

The HTTP status code on the response is meaningful too.

Status code summary

Status	Meaning
200	Success
201	Created
204	Success, no body (delete operations)
400	Bad request — invalid input, validation failure
401	Unauthenticated — missing or invalid bearer token
403	Authenticated but forbidden — missing scope, consent, allowlist match
404	Resource not found
409	Conflict — duplicate idempotency key with different body, state-machine violation
410	Gone — resource was deleted
422	Unprocessable entity — validated but semantically invalid (e.g., user has no payout destination)
429	Rate limited — `Retry-After` header tells you when to try again
500	Internal server error — our problem, retry with exponential backoff
502 / 503 / 504	Upstream temporarily unavailable — retry with backoff

Error code reference

Authentication errors (401, 403)

Code	HTTP	Cause	What to do
`missing_auth`	401	No `Authorization` header	Add the bearer token
`invalid_auth`	401	Token doesn’t match an active key	Check the value; rotate if compromised
`ip_not_allowed`	401	Source IP not in allowlist	Add the IP, or remove allowlisting
`scope_insufficient`	403	Token’s scopes don’t cover the operation	Use a key with the required scope

Code	HTTP	Cause	What to do
`consent_missing`	403	No `X-Guild-Consent-Token` header on a snapshot read	Add the header
`consent_not_found`	403	Consent ID doesn’t exist or isn’t yours	Verify the ID; generate a new consent if needed
`consent_revoked`	403	User revoked the consent	Ask the user to re-grant
`consent_expired`	403	Consent passed its `expiresAt`	Generate a new consent link, ask the user to renew
`consent_scope_mismatch`	403	The consent doesn’t include the scope you’re requesting	Generate a new consent with the right scopes

Validation errors (400, 422)

Code	HTTP	Cause
`invalid_input`	400	Request body failed schema validation. See `details` array for specifics.
`missing_field`	400	A required field is absent.
`invalid_field_value`	400	A field has the wrong type or shape.
`invalid_amount`	422	Amount is below minimum, above maximum, or zero.
`user_not_eligible`	422	User doesn’t meet the operation’s prerequisites (e.g., disbursement to a user with no Tier 3 KYC).
`user_no_payout_destination`	422	Disbursement target user has no verified payout account.
`amount_above_limit`	422	Amount exceeds the user’s or your account’s per-transaction limit.

Resource errors (404, 409, 410)

Code	HTTP	Cause
`user_not_found`	404	The user ID doesn’t exist or has been deleted/anonymised.
`consent_not_found`	404	The consent ID doesn’t exist (different from `403 consent_not_found` which is “exists but isn’t yours”).
`webhook_not_found`	404	The webhook subscription ID doesn’t exist.
`disbursement_not_found`	404	The disbursement ID doesn’t exist or doesn’t belong to you.
`idempotency_conflict`	409	The same `Idempotency-Key` was used previously with a different request body.
`state_conflict`	409	Operation not allowed in the current state (e.g., cancel a disbursement that already settled).
`resource_gone`	410	The resource was deleted.

Rate limiting (429)

Code	HTTP	Cause	What to do
`rate_limited`	429	Exceeded per-key request rate	Wait `Retry-After` seconds; consider exponential backoff

Server errors (5xx)

Code	HTTP	Cause	What to do
`internal_error`	500	An unexpected error on our side	Retry with exponential backoff; include `requestId` in support if persistent
`upstream_unavailable`	502	A downstream dependency (OPay, etc.) is temporarily unavailable	Retry with backoff
`service_unavailable`	503	Maintenance or temporary capacity issue	Retry with backoff
`upstream_timeout`	504	Downstream took longer than expected	Retry with backoff; the operation may have succeeded — use idempotency to check

Retry guidance

Error class	Retry safe?	Strategy
4xx (except 429)	No	Fix the request; retry won’t help
429	Yes	Wait `Retry-After`, then retry
5xx	Yes	Exponential backoff with jitter; max 5 attempts
Network failure (no response)	Yes if idempotent	Retry with same `Idempotency-Key`

For write operations, always include an Idempotency-Key. A 5xx response on a write may indicate the operation succeeded but the response was lost; retrying with the same key will either return the prior result or proceed if it never started.

A debugging walkthrough

You get a 403 consent_revoked on a snapshot read. The path forward:

Check the response

code: consent_revoked, requestId: req_01HMFB.... Note the request ID.

Verify the consent state

GET /partner/v1/consents/<your_consent_id>. Returns the consent record. Confirm status is REVOKED.

Check when it was revoked

revokedAt field on the consent. Compare against your records.

Generate a new consent

POST /partner/v1/consent-links with the user’s phone and desired scopes.

Send the consent link to the user

Through your application’s notification path.

Wait for the consent.granted webhook

Or check /consents/:id polling — webhook is the preferred path.

Retry the snapshot read with the new consent token

Should succeed now.

Request IDs

Every response (success or error) includes a request ID. Include it in any support ticket and we can correlate immediately. Request IDs are also visible in your Partner Portal dashboard’s audit log.

Snapshots

The endpoint reference.

Rate limits

Throughput numbers and burst behaviour.

Get Started

Partner API

Webhooks

Status code summary

Error code reference

Authentication errors (401, 403)

Validation errors (400, 422)

Resource errors (404, 409, 410)

Rate limiting (429)

Server errors (5xx)

Retry guidance

A debugging walkthrough

Request IDs

What to read next

Snapshots

Rate limits

​Status code summary

​Error code reference

​Authentication errors (401, 403)

​Consent errors (403)

​Validation errors (400, 422)

​Resource errors (404, 409, 410)

​Rate limiting (429)

​Server errors (5xx)

​Retry guidance

​A debugging walkthrough

​Request IDs

​What to read next

Snapshots

Rate limits

Status code summary

Error code reference

Authentication errors (401, 403)

Consent errors (403)

Validation errors (400, 422)

Resource errors (404, 409, 410)

Rate limiting (429)

Server errors (5xx)

Retry guidance

A debugging walkthrough

Request IDs

What to read next