Errors

The response envelope, HTTP status codes, and what a failed transaction's reason means.

Response envelope

Every response, success or failure, has the same shape:

{
  "success": true,
  "message": "payment initiated",
  "data": { }
}

successbooleanrequired

Whether the request succeeded. Check this before reading data.

messagestringrequired

What happened. On failure, says what went wrong in words you can show a user.

dataobject | array | nullrequired

The endpoint’s result. null on failure.

Status codes

Code	Meaning
`400`	The request can’t be done as sent: a missing field, an invalid phone number, a limit exceeded, a provider that isn’t enabled. `message` says which.
`401`	Missing, unknown or revoked API key.
`403`	The key lacks the permission this endpoint needs.
`404`	Nothing with that reference in your project.
`429`	Too many requests. See Rate limits.
`500`	Something went wrong on our side. Safe to retry with the same `external_reference`.

{
  "success": false,
  "message": "provider \"momo\" is not enabled for this project",
  "data": null
}

A 400 from a write means nothing was created, with one exception: if the provider rejects the request after RazPay recorded it, the transaction exists as failed and the message starts failed to initiate payment:, failed to send payout: or failed to send refund:, followed by the reason.

Failure reasons

A failed transaction’s failure_reason is a plain-language explanation built from the provider’s error code. These are the common ones from MTN MoMo:

Reason	What to do
`payer account could not be found`	The number isn’t a MoMo wallet. Check it with the customer.
`payee account could not be found`	The payout number isn’t a MoMo wallet.
`payment was rejected by the payer`	The customer declined the prompt.
`payment request expired before it was approved`	The customer didn’t approve in time.
`payment timed out before it was approved — approve within 5 minutes`	Same: ask the customer to try again and approve quickly.
`insufficient funds`	The paying wallet (or your disbursement account) lacks the balance.
`payer has reached their transaction limit`	The customer has hit their wallet limit.
`this payment is not allowed`	MTN refused the operation for this account; contact your MTN account manager.
`currency is not supported for this account`	Use the currency of your MTN environment (`SZL` in Eswatini production).
`payment provider is temporarily unavailable, please try again shortly`	Retry later.

MTN sometimes returns codes it doesn’t document. Those come through as the code in plain words (SOME_NEW_CODE becomes some new code), so you always learn something concrete.