Error response format
Every error response contains anerrors array with one or more error objects:
Metadata
Public error responses includemeta.supportId by default. Natural keeps internal detail in its logs, keyed by supportId. A rate-limited or capped request may also carry meta.retryAfter (an RFC 3339 timestamp) and, on a card payment cap, meta.limitScope (merchant or program). The exception is external account errors that can be repaired by relinking: those may also include meta.connectionStatus (login_required or disconnected) and meta.provider with the provider’s error code, type, and request ID.
Rate limit errors
Requests over the rate limit receive a429 with code rateLimited. The response carries a Retry-After header with the seconds to wait before retrying. See Rate limits.
Sandbox simulation errors
Sandbox simulations can return408 with code sandbox.notReady while an action is still becoming ready or its result is not visible yet. Wait for the number of seconds in Retry-After, then retry the same request. If you supplied an Idempotency-Key, reuse it so the retry cannot create a second operation.
Not implemented and MFA required
The API reference lists501 and 428 on every endpoint. In practice:
notImplemented(501): a Natural service behind the API does not support the request yet. It is a fault on Natural’s side, not in your request. Send feedback withPOST /feedback, and include themeta.supportIdfrom the response.mfa.required(428): no API endpoint returns this code today.
Validation errors
Validation responses contain one error object for each invalid request value. Eachdetail gives
a safe, schema-specific reason, while source.pointer identifies the exact location in the request.
invalidValue is 422 for a request-shape failure and 400 for a well-formed value the endpoint
cannot accept:
Generic errors
These errors are not tied to one resource. The per-resource error pages list only the codes specific to each resource.idempotencyKeyReused and idempotencyRequestInProgress apply only to requests that send an Idempotency-Key. See Idempotency.
Cross-cutting errors
Permission errors
A403 can mean that a key or token lacks a required permission, or that the current
customer connection does not permit the action. When Natural can identify the cause,
detail names the required permission. For example:
This customer connection does not currently allow this action. Required permission: wallets.withdraw.Check the permission named in
detail before retrying. A connection can allow one action,
such as sending payments, without allowing another, such as depositing funds.
Some access errors remain generic to protect private resource information.
Use code and status for programmatic error handling. Display detail to explain the
failure; its wording can change.