Errors

The NahuPay API uses conventional HTTP status codes to indicate success or failure. Errors include a machine-readable code and a human-readable message.

Error format

{
  "error": {
    "code":    "invalid_amount",
    "message": "Amount must be a positive integer in ETB cents.",
    "param":   "amount"   // present when the error is tied to a specific field
  }
}

Field	Type	Description
`code`	`string`	Machine-readable error code — safe to switch on.
`message`	`string`	Human-readable description. Do not display to end users.
`param`	`string \| null`	The request field that caused the error, if applicable.

Error codes

Code	Status	Description
`invalid_amount`	`400`	Amount must be a positive integer in ETB cents.
`invalid_currency`	`400`	Only ETB is supported.
`invalid_method`	`400`	Unknown payment method identifier.
`missing_param`	`400`	A required parameter is missing. See error.param.
`invalid_url`	`400`	success_url or cancel_url is not a valid HTTPS URL.
`authentication_failed`	`401`	API key is missing, malformed, or revoked.
`account_not_verified`	`403`	Live key used but KYB is not complete.
`payment_not_found`	`404`	No payment with that ID exists on this account.
`idempotency_conflict`	`409`	Idempotency key reused with different parameters.
`rate_limit_exceeded`	`429`	Too many requests. Check the Retry-After header.
`payment_gateway_error`	`502`	Upstream provider error. Retry after a short delay.
`internal_error`	`500`	Unexpected server error. Contact support if it persists.

Handling errors in code

All SDKs surface errors as typed exceptions:

import NahuPay, { NahuPayError } from 'nahupay';try {const payment = await client.payments.create({ amount: -1, currency: 'ETB' });} catch (err) {if (err instanceof NahuPayError) {console.log(err.code);       // "invalid_amount"console.log(err.statusCode);  // 400console.log(err.param);       // "amount"}}