Skip to main content

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.

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 StatusMeaning
200Request processed (check code field for outcome)
400Bad request — invalid payload or missing required fields
401Unauthorized — missing or expired access_token
403Forbidden — insufficient permissions
404Resource not found
422Unprocessable entity — validation error
429Rate limit exceeded — slow down requests
500Internal 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

CodeDescriptionRetryable
00Success—
01Generic errorYes
02Validation error (check description)No
05Transaction not permittedNo
06Error — do not retryNo

​
Authentication codes

CodeDescriptionAction
01Invalid credentialsCheck client_id / client_secret
02Token expiredCall the refresh token endpoint
401UnauthorizedRe-authenticate and get a new access_token

​
Transfer-specific codes

These appear in data.status on transfer responses:
StatusDescriptionAction
SUCCESSTransfer completed immediatelyNo action needed
PENDING_BILLINGTransfer is being processedWait for webhook or poll for status
REFUNDTransfer failed and account was refundedSafe 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

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 [email protected].