Errors & status codes

Status codes

Status	Meaning	Do this
`200` / `201`	Success	—
`400`	Validation failed, or a verified payment’s amount didn’t match	Read `error.details`; fix the field or amount and resend
`401`	Token missing or expired	Re-call `/generate-token`, retry once (Authentication)
`403`	Token lacks the required scope	Check your key’s scopes in the Dashboard
`404`	Resource not found	Verify the ID and that it exists in this environment
`409`	Conflict (duplicate idempotency reference in flight)	Reuse the same reference; do not generate a new one
`422`	Semantically invalid (e.g. amount outside product limits)	Adjust to the product’s min/max
`5xx`	Upstream/bank error	Retry with backoff; if it persists, contact Support

Common cases

401 after it was working

Your token expired (~1h TTL). Clear it, call /generate-token again, and retry the request once. Cache the new token until expiresAt.

Customer can't hold a wallet or loan

The customer isn’t ACTIVE. Run the KYC onboarding flow: submit documents, then PATCH .../activate. Activation may require manual review.

submit-payment returned 400

Bridge verified the payment on the gateway and the amount didn’t match (or the gatewayReference wasn’t found yet). Confirm the collection completed and the amount matches before resubmitting.

Every recipe shows the 401 → re-token → retry path inline, so you rarely hit these by surprise.

Getting started

Core concepts

Build with AI

Errors & status codes

Status codes

Common cases

​Status codes

​Common cases

Status codes

Common cases