Errors
The PaymentGateway error envelope, error-code ranges, and the live error catalog.
Every error response uses one consistent JSON envelope, so you can handle all failures with a single code path.
The error envelope
{
"object": "error",
"location": "/v1/charges",
"message": "Charge not found",
"code": 4100,
"key": "E4100",
"i18n_key": "charge.not_found",
"request_id": "req_01HZX…"
}| Field | Type | Description |
|---|---|---|
object | string | Always "error". |
location | string | The service-internal path that produced the error (e.g. /v1/charges). This is the wallet's internal mount, not the full public request path. |
message | string | Human-readable English fallback message. |
code | number | Stable numeric error code (e.g. 4100). |
key | string | String variant of the code (E<code>, e.g. E4100). Branch on this, not the message. |
i18n_key | string | Dot-notation translation key for localized UI text. May be empty if not yet translated. |
request_id | string | Per-request correlation id — include it when reporting issues to support. |
The HTTP status code matches the error (e.g. 404 for E4100, 402 for a
declined card). Always branch on key / code; never parse the message
string, which is a fallback and may change.
Error-code ranges
Codes are grouped by domain. The first digit indicates the area:
| Range | Domain |
|---|---|
1000–1499 | Internal, validation, authentication & authorization |
2000–2499 | Infrastructure (database, cache, broker, storage, upstream) |
3000–3599 | Accounts, IAM, service accounts, roles, credentials |
4100–4899 | Payments: charges, invoices, payouts, transfers, refunds, quotes, credit notes, receipts |
5100–5599 | Subscriptions, schedulers, products, coupons, fees, shipping, meters |
6100–6499 | Customers, balances, payment methods, bank accounts |
7100–7399 | Tax, forex, currencies |
8100–8999 | Webhooks, SDK, files, logs, analytics |
Frequently seen codes
| Key | HTTP | Meaning |
|---|---|---|
E1101 | 400 | Request validation failed |
E1200 | 401 | Authentication required |
E1211 | 401 | Invalid or inactive secret key |
E1300 | 403 | Insufficient permissions |
E1401 | 409 | Idempotency key replay detected |
E2001 | 404 | Record not found |
E4100 | 404 | Charge not found |
E4107 | 400 | Charge amount must be greater than 0 |
E4116 | 400 | PromptPay charges support only automatic capture |
E4150 | 402 | Card was declined |
E4153 | 402 | Insufficient funds |
E6100 | 404 | Customer not found |
E6209 | 400 | balance_id is required for customer balance operations |
E8888 | 404 | Resource not found |
The live catalog
The complete, always-current catalog is served by the API at
{WALLET}/errors/catalog, where $WALLET is your API base
({base_url}/api/v1/{app}/platform/wallet — see
Quick guide):
curl "$WALLET/errors/catalog"Each entry returns its code, key, i18n_key, HTTP status, severity, and the
English fallback message. Build your client's error map from this endpoint rather
than hardcoding the full list — new codes are added as features ship.
A point-in-time snapshot of the catalog also lives in the repository at
docs/wallet/ERRORS.mdfor offline reference.