Error Codes

HTTP status codes and application error codes from the Gateway API.

Error format

Failed process-transfer calls return success: false with an error object. Validation errors use Nest's standard format.

Transfer error

{
  "success": false,
  "message": "Insufficient wallet balance",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Partner escrow wallet balance is insufficient"
  }
}

Validation error

{
  "statusCode": 400,
  "message": ["phoneNumber: Phone number must be a valid Uganda number (256XXXXXXXXX)"],
  "error": "Validation Failed"
}

Error reference

Code	HTTP	Description
TRANSACTION_NOT_FOUND	404	No transaction matches the given ID or partner reference.
INSUFFICIENT_BALANCE	400	Partner wallet balance too low for send modes.
TRANSFER_FAILED	400	Transfer rejected by provider or internal processing.
INVALID_REQUEST	400	Invalid transaction mode or missing required fields.
Validation Failed	400	Request body failed class-validator checks.
Unauthorized	401	Missing, invalid, expired, or revoked API key.
Too Many Requests	429	Partner rate limit exceeded.