Reference
Errors
Every error shares one envelope shape and a stable code you can branch on, the message text may change, the code won't.
Error shape
→ 4xx/5xx
{
"status": false,
"message": "Human-readable, for logs/debugging",
"code": "merchant_cap_exceeded",
"meta": {}
}Stable codes
| Code | HTTP | Meaning |
|---|---|---|
| validation_error | 422 | Request body failed validation. |
| unauthorized | 401 | Missing, invalid, or expired credentials. |
| not_found | 404 | The resource doesn't exist, or doesn't belong to this credential. |
| email_taken | 409 | An account/team member with this email already exists. |
| invalid_state | 409 | The resource isn't in a state that allows this action (e.g. refunding a non-SUCCESS charge). |
| session_expired | 410 | The checkout/payment session's expiry window has passed. |
| insufficient_tier | 403 | Your account role doesn't permit this action, or your KYC tier caps it. |
| kyc_required | 403 | Business KYC must be completed before this action (e.g. going live). |
| merchant_cap_exceeded | 403 | This charge would exceed your Starter-tier rolling collection cap. Upgrade to Registered to lift it. |
| idempotency_conflict | 409 | The same Idempotency-Key was reused with a different request body. |
| invalid_signature | 401 | Inbound webhook signature (bank or WhatsApp) didn't verify. |
| core_unavailable | 503 | The money-core service is temporarily unreachable. Safe to retry. |
| not_implemented | 501 | Feature not available yet on the current bank rail/tier (e.g. live card payments). |