Authentication
401 — Invalid credentials
Expired or missing Bearer token.
403 — Forbidden
Verification or feature gates.
Validation & state
422 — Validation errors
Payload and field fixes.
Duplicate reference_id
Idempotency conflicts.
Session expired
Stale or wrong session_id.
Payments & operations
Stuck in PROCESSING
Normal MoMo delays vs real failures.
Card 3DS failed
requires_action and client_secret.
Payout passcode
Passcode setup and payload errors.
Wallet balance
Payout failed — low wallet balance.
429 — Rate limit
Backoff and Retry-After.
5xx — Server errors
When to retry and escalate.