Skip to main content
All errors from the UBN BaaS API follow the RFC 7807 Problem Details standard: a consistent format used across every endpoint. Every error includes a human-readable explanation you can read while debugging, and a machine-readable 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 the code field in the body for the specific cause.

Error Codes

Use the code 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

For 429 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.
For 429 errors, check the Retry-After response header first. It tells you the exact number of seconds to wait. Use that value instead of the exponential backoff when present, as it reflects the actual rate limit window rather than an estimate.

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:
  1. The response status is 503 with code CIRCUIT_BREAKER_OPEN.
  2. The X-Circuit-Breaker-Open: true header is present in the response.
  3. Wait 30 seconds before retrying.
  4. The circuit closes automatically once the downstream service recovers.
You can check real-time service status at api-partner.onecluster.co/status.

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 correlationId from the error response body
  • The endpoint you were calling
  • The error code and 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.