Skip to main content
Bridge returns standard HTTP status codes with a JSON error body: 
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid userId value supplied",
    "details": { "field": "userId" }
  }
}

​
Status codes

StatusMeaningDo this
200 / 201Success—
400Validation failed, or a verified payment’s amount didn’t matchRead error.details; fix the field or amount and resend
401Token missing or expiredRe-call /generate-token, retry once (Authentication)
403Token lacks the required scopeCheck your key’s scopes in the Dashboard
404Resource not foundVerify the ID and that it exists in this environment
409Conflict (duplicate idempotency reference in flight)Reuse the same reference; do not generate a new one
422Semantically invalid (e.g. amount outside product limits)Adjust to the product’s min/max
5xxUpstream/bank errorRetry with backoff; if it persists, contact Support

​
Common cases

Your token expired (~1h TTL). Clear it, call /generate-token again, and retry the request once. Cache the new token until expiresAt.
The customer isn’t ACTIVE. Run the KYC onboarding flow: submit documents, then PATCH .../activate. Activation may require manual review.
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.