Skip to main content
All Natural API errors follow a standard JSON:API-style format with stable public codes and safe display copy.

Error response format

Every error response contains an errors array with one or more error objects:
Each error object contains:

Metadata

Public error responses include meta.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 a 429 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 return 408 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 lists 501 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 with POST /feedback, and include the meta.supportId from 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. Each detail 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

A 403 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.

Shared errors

These errors depend on how a request is authenticated and attributed rather than on the resource being called, so the per-resource error pages do not list them. Most apply to requests made with agent credentials or on behalf of another party.