> ## Documentation Index
> Fetch the complete documentation index at: https://developer.nomba.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Codes

> Understand Nomba API response codes and how to handle them

The Nomba API uses a `code` field in the response body to indicate the outcome of every request.

## Response structure

Every Nomba API response follows this structure:

```json theme={null}
{
  "code": String,
  "description": String,
  "data": { ... },
  "message": String,
  "status": boolean
}
```

### Code values

| Code | Meaning |
| - | - |
| `00`, `200`, `201` | Success — request completed successfully |
| `4XX` | Client error — bad request, unauthorized, forbidden, not found, etc. |
| `5XX` | Server error — internal error, retry with backoff |

<Note>
  `4XX` and `5XX` represent standard HTTP status codes (e.g., `400`, `401`, `404`, `500`, `503`).
</Note>

## HTTP status codes

| HTTP Status | Meaning |
| - | - |
| `200` | Request processed successfully |
| `201` | Request accepted and is being processed |
| `400` | Bad request — invalid payload or missing required fields |
| `401` | Unauthorized — missing or expired `access_token` |
| `403` | Forbidden — insufficient permissions |
| `404` | Resource not found |
| `422` | Unprocessable entity — validation error |
| `429` | Rate limit exceeded — slow down requests |
| `500` | Internal server error — retry with backoff |

<Note>
  A `2XX` HTTP status generally means the HTTP request was successful against the Nomba API gateway. As for the response `code` value and `data.status` value (for transaction-based requests), please check specific request documentation for any additional information.

  For safety, if an undocumented `code` or `data.status` is returned for a transaction-based request, perform a requery to confirm the transaction state, or wait for a webhook before deciding. **Do not refund unless the `payout_refund` webhook is received or the requery returns `data.status` = `REFUND`.**
</Note>

<Tip>
  Seeing a spike in `500` errors or timeouts? Check [status.nomba.com](https://status.nomba.com) to see if there is an ongoing incident before you debug your integration.
</Tip>

## Outflow (Transaction Status)

These appear in `data.status` on outflow responses (transfers, airtime, data, bills, etc.):

| Status | What happened | Refund customer? |
| - | - | - |
| `SUCCESS` | Service delivered to destination | No |
| `REFUND` | Funds returned to your Nomba wallet | Yes |
| `CANCELLED` | Transaction will not proceed | Contact support |
| `PAYMENT_FAILED` | Debit failed, Nomba may retry | Wait for webhook |
| `REVERSED_BY_VENDOR` | Nomba may retry via another vendor | Wait for webhook |
| `PENDING_BILLING` | Still processing | Wait for webhook |
| `PROCESSING` | Still processing (v1 endpoints) | Wait for webhook |

<Note>
  Nomba-to-Nomba wallet transfers (`/v2/transfers/wallet`) do not return a `sessionId`. Use the parent or sub-account requery endpoints instead.
</Note>

## Handling errors in code

<CodeGroup>
  ```javascript Node.js theme={null}
  async function makeTransfer(payload) {
    const response = await fetch('https://api.nomba.com/v2/transfers/bank', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'accountId': accountId,
      },
      body: JSON.stringify(payload),
    });

    const result = await response.json();

    const successCodes = ['00', '200', '201'];
    if (!successCodes.includes(result.code)) {
      // Handle error based on result.code
    }

    const { status } = result.data;

    if (status === 'SUCCESS') {
      // Service delivered to destination — no refund needed
    }

    if (status === 'REFUND') {
      // Funds returned to your Nomba wallet — refund customer
    }

    if (status === 'CANCELLED') {
      // Transaction will not proceed — contact support
    }

    if (status === 'PAYMENT_FAILED') {
      // Debit failed, Nomba may retry — wait for webhook
    }

    if (status === 'REVERSED_BY_VENDOR') {
      // Nomba may retry via another vendor — wait for webhook
    }

    if (status === 'PENDING_BILLING') {
      // Still processing — wait for webhook
    }
  }
  ```

  ```python Python theme={null}
  import requests

  def make_transfer(payload, access_token, account_id):
      response = requests.post(
          'https://api.nomba.com/v2/transfers/bank',
          headers={
              'Authorization': f'Bearer {access_token}',
              'Content-Type': 'application/json',
              'accountId': account_id,
          },
          json=payload,
      )

      result = response.json()

      success_codes = ['00', '200', '201']
      if result['code'] not in success_codes:
          # Handle error based on result['code']
          pass

      status = result['data']['status']

      if status == 'SUCCESS':
          # Service delivered to destination — no refund needed
          pass

      if status == 'REFUND':
          # Funds returned to your Nomba wallet — refund customer
          pass

      if status == 'CANCELLED':
          # Transaction will not proceed — contact support
          pass

      if status == 'PAYMENT_FAILED':
          # Debit failed, Nomba may retry — wait for webhook
          pass

      if status == 'REVERSED_BY_VENDOR':
          # Nomba may retry via another vendor — wait for webhook
          pass

      if status == 'PENDING_BILLING':
          # Still processing — wait for webhook
          pass
  ```
</CodeGroup>

## Rate limit errors

If you exceed the rate limit, you'll receive a `429` HTTP status. See the [Rate Limits](/docs/api-basics/rate_limit) page for limits per endpoint.

```json theme={null}
{
  "code": "429",
  "description": "Too many requests. Please slow down.",
  "data": null
}
```

**Transfer-specific:** There is a limit of **5 bank transfers to the same recipient per minute**. Space out repeat transfers or implement a queue.

## Need help?

If you receive an error code not listed here or need help debugging, first check [status.nomba.com](https://status.nomba.com) for any ongoing incidents, then contact [docs@nomba.com](mailto:docs@nomba.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.