Developer Documentation

Error Codes

All errors use the standard error response body.

VALIDATION_ERROR - request body or query parameters failed validation.
UNAUTHENTICATED - bearer token is missing.
INVALID_TOKEN - access token is invalid or expired.
INVALID_REFRESH_TOKEN - refresh token is invalid, expired, or revoked.
FORBIDDEN - authenticated user does not have the required role.
RATE_LIMITED - per-minute request limit exceeded.
IDEMPOTENCY_KEY_REQUIRED - financial creation request is missing a valid key.
IDEMPOTENCY_CONFLICT - same idempotency key was reused with a different request body.
INVALID_TRANSACTION_PIN - transaction PIN check failed.
PIN_TEMPORARILY_LOCKED - too many failed transaction PIN attempts.
OTP_INVALID_OR_EXPIRED - OTP code is invalid, expired, consumed, or not found.
OTP_RESEND_TOO_SOON - OTP resend frequency limit triggered.
OTP_ATTEMPTS_EXCEEDED - OTP max attempts exceeded.
DEVICE_ID_REQUIRED - device ID is required for the protected financial action.
QR_NOT_VERIFIED - merchant QR token/code pair could not be verified.
INVALID_GHANA_CARD - Ghana Card number does not match expected format.
KYC_FILE_REQUIRED - KYC document upload is missing.
INVALID_KYC_FILE_TYPE - KYC file extension is not allowed.
KYC_FILE_TOO_LARGE - KYC upload exceeds max size.
INSUFFICIENT_FUNDS - wallet balance cannot cover the debit.
WALLET_NOT_FOUND - active wallet was not found for the actor or requested wallet ID.
MERCHANT_NOT_VERIFIED - merchant is missing or inactive.
PAYMENT_NOT_FOUND - payment ID was not found.
INVALID_PAYMENT_STATUS - payment cannot transition from its current status.
INVALID_WITHDRAWAL_STATUS - withdrawal cannot transition from its current status.
WEBHOOK_SIGNATURE_REQUIRED - webhook signature header is missing.
INVALID_WEBHOOK_SIGNATURE - webhook HMAC verification failed.
PROVIDER_CONFIG_NOT_FOUND - requested provider configuration does not exist.
SETTLEMENT_NOT_FOUND - requested settlement does not exist.
RECONCILIATION_RUN_NOT_FOUND - requested reconciliation run does not exist.
PROVIDER_TRANSACTION_NOT_FOUND - requested provider transaction does not exist.
USER_NOT_FOUND - requested user does not exist.
FRAUD_RULE_NOT_FOUND - requested fraud rule does not exist.
REVERSAL_REQUEST_NOT_FOUND - requested reversal request does not exist.
INVALID_REVERSAL_STATUS - reversal cannot transition from its current state.
RATE_LIMITED - the request exceeded endpoint, user, IP, or API key limits.
LIMIT_EXCEEDED - mobile payment or withdrawal exceeds configured transaction limits.
CASH_CONFIRMATION_REQUIRED - merchant must confirm cash payout before completing withdrawal.
DEVICE_NOT_TRUSTED - mobile device requires additional trust verification.
PROVIDER_UNAVAILABLE - external payment provider is not available.
HTTPS_REQUIRED - production request was not sent over HTTPS.
INTERNAL_SERVER_ERROR - unexpected server error.

Financial reversal note: transaction rows and ledger entries are immutable. Failed corrections should create reversal transactions and reversal ledger entries instead of updating historical ledger rows.