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"
  }
}
HTTPTypical error.codeWhen
400VALIDATION_ERRORMissing 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).
403ABILITY_DENIEDThe credential is scoped and this call is outside its scope. Unscoped credentials never see this
403CONDITION_FAILEDThe 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)
403FIELD_EXCLUDEDThe request writes, filters by, or declares by a field the credential cannot read. Refused before anything is stored
403ESCALATION_REFUSEDMinting an unscoped key without the grants that key would carry
404NOT_FOUNDTransaction, customer, deposit, webhook, or delivery does not exist for this merchant
429RATE_LIMITEDThrottle; wait and retry. Nothing is stored
500EXTERNAL_SERVICE_ERRORBanking partner failure; error.message includes the provider reason when available
500INTERNAL_ERRORUnexpected 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

HTTPerror.codeWhen
400RESERVED_CUSTOMER_REFERENCEThe reference is LEGACY_UNSET, in any letter case
400INVALID_EXPIRYexpiresAt is in the past or more than 30 days ahead
400CUSTOMER_INCOMPLETEA payout or declaration by id names a customer missing details the request needs. error.details.missingFields lists them
400CUSTOMER_CURRENCY_MISMATCHThe customer is held in a different currency from this request
400CUSTOMER_UNBOUNDA declaration by id names a customer with no reference and sends none. A payout by id does the same once strict mode is on
400IMMUTABLE_FIELDOnce strict mode is on, an edit of a customer's rail, IBAN, account number, routing number, or a currency that is already set
409CUSTOMER_EXISTSCreating or editing a customer would duplicate an active one. error.details.customerId is present only when you may read that customer
409CUSTOMER_REFERENCE_CONFLICTThe customer is already linked to another customer reference. The message never says which
409IDEMPOTENCY_KEY_REUSEDA deposit's idempotencyKey was already used with different content, including a different receiving account
409CONFLICTThe customer or declaration changed while the request was being processed. Retry it

Rate limits

SurfaceLimit
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 payout20 / minute
Register, delete, or replay a webhook10 / 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.


Did this page help you?