Errors & rate limits
Error envelope
Failures use this shape (not a raw Nest statusCode body):
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "idempotencyKey should not be empty",
"details": [{ "field": "idempotencyKey", "message": "idempotencyKey should not be empty" }]
},
"meta": {
"correlationId": "…",
"timestamp": "2026-09-11T09:00:00.000Z"
}
}| HTTP | Typical error.code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or invalid body, or a business rule (unknown account, currency mismatch, insufficient funds, non-HTTPS webhook URL, invalid IBAN) |
| 401 | — | Missing or wrong Basic credentials, revoked key, or lockout. Message is Invalid API credentials. The code field may read TOKEN_EXPIRED (shared error map; it does not mean a JWT expired). |
| 403 | ABILITY_DENIED | The credential is scoped and this call is outside its scope. Unscoped credentials never see this |
| 403 | CONDITION_FAILED | The credential holds the permission but this request is outside its conditions (customer, payout, deposit, account, or a webhook set/replay without unrestricted reads of transactions, payouts and deposits) |
| 403 | FIELD_EXCLUDED | The request writes, filters by, or declares by a field the credential cannot read. Refused before anything is stored |
| 403 | ESCALATION_REFUSED | Minting an unscoped key without the grants that key would carry |
| 404 | NOT_FOUND | Transaction, customer, deposit, webhook, or delivery does not exist for this merchant |
| 429 | RATE_LIMITED | Throttle; wait and retry. Nothing is stored |
| 500 | EXTERNAL_SERVICE_ERROR | Banking partner failure; error.message includes the provider reason when available |
| 500 | INTERNAL_ERROR | Unexpected failure — send meta.correlationId to Enovipay |
GET and successful POST/PUT return the resource directly (no { success: true } wrapper). Branch on error.code, never on the message.
Codes for customers, deposits and payouts
| HTTP | error.code | When |
|---|---|---|
| 400 | RESERVED_CUSTOMER_REFERENCE | The reference is LEGACY_UNSET, in any letter case |
| 400 | INVALID_EXPIRY | expiresAt is in the past or more than 30 days ahead |
| 400 | CUSTOMER_INCOMPLETE | A payout or declaration by id names a customer missing details the request needs. error.details.missingFields lists them |
| 400 | CUSTOMER_CURRENCY_MISMATCH | The customer is held in a different currency from this request |
| 400 | CUSTOMER_UNBOUND | A declaration by id names a customer with no reference and sends none. A payout by id does the same once strict mode is on |
| 400 | IMMUTABLE_FIELD | Once strict mode is on, an edit of a customer's rail, IBAN, account number, routing number, or a currency that is already set |
| 409 | CUSTOMER_EXISTS | Creating or editing a customer would duplicate an active one. error.details.customerId is present only when you may read that customer |
| 409 | CUSTOMER_REFERENCE_CONFLICT | The customer is already linked to another customer reference. The message never says which |
| 409 | IDEMPOTENCY_KEY_REUSED | A deposit's idempotencyKey was already used with different content, including a different receiving account |
| 409 | CONFLICT | The customer or declaration changed while the request was being processed. Retry it |
Rate limits
| Surface | Limit |
|---|---|
Declare a deposit (POST /v1/deposits) | 120 / minute per client IP, in a tier of its own |
Reads (GET accounts, balance, transactions, customers, payouts, deposits) | 20 / minute in practice |
| Create, update, or delete a customer; create a payout | 20 / minute |
| Register, delete, or replay a webhook | 10 / minute |
Other /v1 calls (GET /v1/webhook, GET /v1/webhook/deliveries) | 20 / minute in practice |
Limits are counted per route and per client IP, not per credential. The shared 20-a-minute tiers also count reads, so plan polling around 20, not 60, and prefer the webhook for outcomes.
Updated 15 days ago
Did this page help you?
