Errors | NuruPay Docs

Errors use standard HTTP status codes and one JSON shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone",
    "message": "phone must be a valid Tanzanian mobile number",
    "param": "phone",
    "request_id": "req_01M3P44HNMABSHMWA98XWDH8XP"
  }
}

Branch on code (stable). message is for humans and may change.
param names the field at fault, when there is one.
Quote request_id (also in the X-Request-Id header) when contacting support.

Status	`type`	Common codes
400	`invalid_request_error`	`invalid_phone`, `unsupported_currency`, `unsupported_channel`, `invalid_reference`, `invalid_metadata`, `invalid_json`, `idempotency_key_required`, `invalid_idempotency_key`, `invalid_limit`
401	`authentication_error`	`invalid_api_key`, `api_key_expired`
403	`permission_error`	`live_mode_not_enabled`, `merchant_suspended`, `ip_not_allowed`
404	`invalid_request_error`	`resource_not_found`
409	`invalid_request_error`	`duplicate_reference`, `idempotency_key_reused`, `idempotency_request_in_progress`
422	`invalid_request_error`	`amount_too_small`, `amount_too_large`, `unsupported_channel` (network not detected from the number)
429	`rate_limit_error`	`rate_limited`
500	`api_error`	`internal_error`: safe to retry with the same idempotency key

A payment that is declined is not an HTTP error: the collection is returned normally with status: "failed" and a failure_code.

`failure_code`	Meaning
`insufficient_funds`	Not enough money in the customer's wallet.
`customer_cancelled`	The customer rejected the PIN prompt.
`customer_timeout`	The customer did not respond in time.
`invalid_account`	The number cannot receive this payment.
`account_not_registered`	The number is not registered for this network's mobile money.
`limit_exceeded`	The amount exceeds a wallet or network limit.
`provider_rejected`	The network declined the payment.
`provider_unavailable`	The network was unavailable.