Error Codes

Understand Nomba API error codes and how to handle them

The Nomba API uses a code field in the response body to indicate the outcome of every request. A successful response always returns "code": "00". All other codes indicate an error or a specific state you need to handle.

Response structure

Every Nomba API response follows this structure:

{
  "code": "00",
  "description": "Success",
  "data": { ... }
}

On errors, data is typically null and description explains what went wrong:

{
  "code": "02",
  "description": "amount can not be null",
  "data": null
}

HTTP status codes

HTTP Status	Meaning
200	Request processed (check code field for outcome)
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

A 200 HTTP status does not always mean success. Always check the code field in the response body.

API response codes

General codes

Code	Description	Retryable
00	Success	—
01	Generic error	Yes
02	Validation error (check description)	No
05	Transaction not permitted	No
06	Error — do not retry	No

Authentication codes

Code	Description	Action
01	Invalid credentials	Check client_id / client_secret
02	Token expired	Call the refresh token endpoint
401	Unauthorized	Re-authenticate and get a new access_token

Transfer-specific codes

These appear in data.status on transfer responses:

Status	Description	Action
SUCCESS	Transfer completed immediately	No action needed
PENDING_BILLING	Transfer is being processed	Wait for webhook or poll for status
REFUND	Transfer failed and account was refunded	Safe to retry

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

Handling errors in code

Node.js

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();

  if (result.code !== '00') {
    throw new Error(`Transfer failed: [${result.code}] ${result.description}`);
  }

  const { status } = result.data;

  if (status === 'PENDING_BILLING') {
    // Wait for webhook notification or poll with transaction ID
    return { pending: true, id: result.data.id };
  }

  if (status === 'REFUND') {
    // Transaction failed — safe to retry
    throw new Error('Transfer was refunded. Safe to retry.');
  }

  return result.data;
}

Rate limit errors

If you exceed the rate limit, you’ll receive a 429 HTTP status. See the Rate Limits page for limits per endpoint.

{
  "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, contact [e-mail].