Error Codes

A complete guide to Balad API error codes with clear explanations and resolution steps.

Understanding Error Responses

Response Format

All API errors follow a consistent format:

{
  "data": null,
  "errors": [
    {
      "code": 10,
      "message": "Invalid Input",
      "field": "receiver_bank_code",
      "additional_info": "Bank code must be 3 characters"
    }
  ]
}

Response Fields Explained

Field	Description	Example
`code`	Unique error identifier (use this for programmatic handling)	`10`
`message`	Human-readable error description	`"Invalid Input"`
`field`	The request field that caused the error (when applicable)	`"receiver_bank_code"`
`additional_info`	Extra context to help resolve the issue	`"Bank code must be 3 characters"`

Create Transaction Errors

Endpoint: POST /remit-api/v1/transactions - Create transaction

These errors occur when creating a new transaction.

Input Validation Errors

HTTP	Code	Message	Cause	Resolution
400	`10`	Invalid Input	A request field has an invalid value	Check the `field` and `additional_info` in the response for details. Correct the invalid field and retry.

Amount Errors

HTTP	Code	Message	Cause	Resolution
400	`170`	Minimum amount should be greater than or equal {amount}	Transaction amount is below the minimum threshold	Increase the amount to at least 1 USD (or equivalent in EGP).
400	`171`	Maximum amount should be less than or equal {amount}	Transaction amount exceeds the maximum allowed	Reduce the amount to the maximum shown in the error message.

Transaction Limit Errors

HTTP	Code	Message	Cause	Resolution
400	`187`	Max wallet amount is {amount}	Transaction amount exceeds the maximum wallet limit	Reduce the transaction amount to {amount} EGP or less per wallet transaction.
400	`188`	Recipient account daily transaction limit exceeded	Recipient account has reached the allowed daily transaction limit	Wait until the next day
400	`189`	Recipient account monthly transaction limit exceeded	Recipient account has reached the allowed monthly transaction limit	Wait until the next month

Note

The {amount} value in error messages are dynamic and reflects the actual limits. Always read the exact amount from the API response message rather than assuming a fixed value.

Account & Bank Errors

HTTP	Code	Message	Cause	Resolution
400	`172`	Invalid account number for provided bank code	The receiver's bank account number failed validation	Verify the account number is correct and matches the bank's format requirements. For BDC bank, ensure the account follows their specific format.

Currency & Routing Errors

HTTP	Code	Message	Cause	Resolution
400	`8057`	Sorry, this currency isn't allowed	Unsupported currency code	Use only supported currencies: USD (US Dollar) or EGP (Egyptian Pound).
400	`185`	This currency is not supported on the selected payout route	Currency/route combination not supported	Either change the payout route or use a different currency that's supported on the selected route.

Transaction Type Errors

HTTP	Code	Message	Cause	Resolution
400	`174`	Sorry, this transaction type isn’t allowed.	Invalid or unsupported transaction type	Use only valid transaction types: 1 (Cash), 2 (Account), 3 (Wallet). Contact support if you need a specific type enabled.

Reference Number Errors

HTTP	Code	Message	Cause	Resolution
400	`129`	Reference number already exists	A transaction with this reference already exists	Generate a new unique reference number. Each transaction must have a unique `remitterReferenceNo`.

Balance Errors

HTTP	Code	Message	Cause	Resolution
400	`8068`	The requested amount exceeds your balance	Insufficient partner balance	Pre-fund your account before creating transactions. Contact your account manager to add funds.

Security Errors

HTTP	Code	Message	Cause	Resolution
400	`173`	Encryption must be enabled to process card transactions. Please enable encryption and try again.	Card transaction attempted without encryption	Enable encryption in your partner settings before processing card transactions. Contact support for assistance.

Cancel Transaction Errors

Endpoint: POST /remit-api/v1/transactions/cancel - Cancel transaction

These errors occur when canceling an existing transaction.

HTTP	Code	Message	Cause	Resolution
400	`106`	Invalid Reference Number	Transaction not found	Verify the `remitterReferenceNo` is correct and belongs to your partner account.
400	`113`	Cancellation Not Available	Transaction cannot be canceled in current status	Cancellation is only available for transactions in certain statuses. Check the transaction status first using the status API.
400	`169`	Transaction already canceled before	Transaction was already canceled	No action needed. The transaction is already canceled. Use the transaction details API to confirm the status.

Cancel Error Decision Tree

💡

Is the reference number correct?
├── No → Error 106: Double-check the remitterReferenceNo
└── Yes → Check transaction status
├── Already Canceled → Error 169: No action needed
├── Completed/Transferred → Error 113: Cannot cancel completed transactions
└── Created/Pending → Cancellation should succeed

Update Transaction Errors

Endpoint: POST /remit-api/v1/transactions/update - Update transaction

These errors occur when updating receiver information.

HTTP	Code	Message	Cause	Resolution
400	`106`	Invalid Reference Number	Transaction not found	Verify the `remitterReferenceNo` is correct and belongs to your partner account.
400	`161`	Can not update transaction info	Transaction cannot be updated in current status	Updates are only allowed for transactions in Created status. Transactions that are already transferred, completed, or failed cannot be updated.

Update Error Decision Tree

Is the reference number correct?
├── No  → Error 106: Double-check the remitterReferenceNo
└── Yes → Check transaction status
          ├── Created → Update should succeed
          ├── Processing → Error 161: Wait for completion or contact support
          ├── Transferred/Completed → Error 161: Cannot update completed transactions
          └── Failed/Canceled → Error 161: Cannot update failed/canceled transactions

Developer API Errors

Endpoint: POST /core/v1/developer/secrets - Secrets

HTTP	Code	Message	Cause	Resolution
400	`8033`	You have exceeded the limit of 5 active secrets allowed	Maximum secret count reached	Revoke an existing secret before creating a new one. You can have a maximum of 5 active secrets.

General Errors

These errors can occur on any endpoint.

HTTP	Code	Message	Cause	Resolution
400	`10`	Invalid Input	Request validation failed	Check the `field` and `additional_info` for specific details about what needs to be corrected.
400/500	`14`	An unexpected error has occurred	Unexpected system error	This is rare. Retry the request. If it persists, contact support with your request details and timestamp.

Quick Reference Card

Code	Meaning	Action
`10`	Invalid input	Fix the field shown in response
`14`	System error	Retry, then contact support
`106`	Reference not found	Verify reference number
`113`	Can't cancel	Check transaction status
`129`	Duplicate reference	Use unique reference
`161`	Can't update	Only "Created" status allowed
`169`	Already canceled	No action needed
`170`	Amount too low	Increase amount (min 1 USD)
`171`	Amount too high	Decrease amount
`172`	Invalid account	Verify bank account
`173`	Encryption required	Enable encryption
`174`	Invalid type	Use type 1, 2, or 3
`185`	Currency/route mismatch	Change currency or route
`187`	Wallet limit exceeded	Reduce wallet transaction amount
`188`	Daily recipient limit exceeded	Retry next day
`189`	Monthly recipient limit exceeded	Retry next month
`8033`	Too many secrets	Revoke one first
`8057`	Invalid currency	Use USD or EGP
`8068`	Insufficient balance	Pre-fund account

Error Codes

Quick Navigation#

Understanding Error Responses#

Response Format#

Response Fields Explained#

Create Transaction Errors#

Input Validation Errors#

Amount Errors#

Transaction Limit Errors#

Account & Bank Errors#

Currency & Routing Errors#

Transaction Type Errors#

Reference Number Errors#

Balance Errors#

Security Errors#

Cancel Transaction Errors#

Cancel Error Decision Tree#

Update Transaction Errors#

Update Error Decision Tree#

Developer API Errors#

General Errors#

Quick Reference Card#

Quick Navigation

Understanding Error Responses

Response Format

Response Fields Explained

Create Transaction Errors

Input Validation Errors

Amount Errors

Transaction Limit Errors

Account & Bank Errors

Currency & Routing Errors

Transaction Type Errors

Reference Number Errors

Balance Errors

Security Errors

Cancel Transaction Errors

Cancel Error Decision Tree

Update Transaction Errors

Update Error Decision Tree

Developer API Errors

General Errors

Quick Reference Card