Errors

NamibraPay uses conventional HTTP status codes plus a stable, machine-readable error code so your integration can react programmatically.

The error envelope

Every failure returns success: false, a human-readable error message, an HTTP statusCode, and where applicable a stable code you can branch on.

{
  "success": false,
  "error": "Invalid API key",
  "code": "AUTH_001",
  "statusCode": 401
}

HTTP status codes

Status	Meaning
200 OK	The request succeeded.
201 Created	A resource was created (API key, payment link, plan…).
400 Bad Request	Malformed request body or missing required fields.
401 Unauthorized	No valid API key pair, or your keys are inactive.
403 Forbidden	Authenticated, but not allowed — e.g. live keys before compliance approval.
404 Not Found	The referenced transaction, link or resource doesn't exist.
409 Conflict	The operation clashes with current state — e.g. duplicate checkout completion.
429 Too Many Requests	You exceeded the rate limit. Back off and retry.
500 Internal Server Error	Something failed on our side. Safe to retry with backoff.

Validation errors

Requests that fail field validation return 400 with an errors object that groups messages by field — ready to map straight into your form UI.

{
  "success": false,
  "error": "Validation failed",
  "statusCode": 400,
  "errors": {
    "amount": ["amount must be an integer number of pesewas (whole cedis only)"],
    "channel": ["channel must be one of: mtn_momo, telecel_cash, airteltigo_money, bank_transfer"]
  }
}

Amounts must be whole cedis

Amounts are integers in minor units (pesewas). Fractional amounts like GHS 10.50 are rejected at the edge with a 400 — the provider rails only accept whole cedis.

Error codes

Code	Meaning
AUTH_001	Invalid or missing API key / secret pair
AUTH_002	Session token expired or invalid (dashboard APIs)
BIZ_003	Merchant not approved for live transactions
MER_001	Merchant account is suspended or deactivated
BIZ_007	Checkout already completed or no longer valid
RES_002	Resource not found (unknown transaction reference, link, etc.)
SRV_001	Internal server error — safe to retry with backoff