code field your application can branch on.
For the full shape of an error response, see Error Response Format in the API overview.
Always log the
correlationId from every error response. When you contact support, including the correlationId is the single fastest way to find your request in our systems. It can cut investigation time from hours to minutes.HTTP Status Codes
The HTTP status code gives you the first, broad signal about what went wrong. Read thecode field in the body for the specific cause.
- 2xx Success
- 4xx Client Errors
- 5xx Server Errors
Error Codes
Use thecode field in the error response body to handle specific errors programmatically. The table below covers every code the API can return, what it means, and the exact fix.
Error codes are stable. We will not rename or remove a code without a deprecation period. You can safely use them in
switch statements and conditional logic.Onboarding and Identity
Authentication and Authorisation
Payments and Accounts
Billing and Wallet
Quota and Rate Limiting
Infrastructure and Idempotency
Retry Strategy
For429 Rate Limited and 503 Circuit Breaker Open errors, use exponential backoff with jitter: wait progressively longer between each retry attempt, and add a small random delay to avoid multiple clients hammering the API at the same time.
The recommended sequence: 1 second, then 2 seconds, then 4 seconds, then 8 seconds, then give up and surface the error to the caller.
Circuit Breaker
The circuit breaker protects the platform when a downstream service (the NIP payment network, NIBSS, or an identity verification bureau) experiences degraded performance. When too many requests to a downstream service fail within a short window, the circuit breaker “opens” and all requests that would reach that service are rejected immediately, rather than queuing and timing out. This is a safety mechanism, not a sign that your integration is broken. When the circuit is open:- The response status is
503with codeCIRCUIT_BREAKER_OPEN. - The
X-Circuit-Breaker-Open: trueheader is present in the response. - Wait 30 seconds before retrying.
- The circuit closes automatically once the downstream service recovers.
Getting Help
If you cannot resolve an error using this reference, contact support at baas-support@unionbank.ng. Include the following in your message to get the fastest response:- The
correlationIdfrom the error response body - The endpoint you were calling
- The error
codeand HTTP status - A sanitised version of your request (remove API keys, account numbers, and personal data before sharing)
The
correlationId is the single most important piece of information you can provide. It points directly to your request in our logs, which lets us see exactly what happened: what we received, what was checked, and what failed, without needing to reproduce the issue.
