Error handling

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:

{
  "errors": [
    {
      "code": "insufficient_funds",
      "detail": "Insufficient funds.",
      "status": "409",
      "meta": {
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}

Each error object contains:

Field	Type	Required	Description
`code`	string	Yes	Stable lower-snake-case public error code (e.g., `insufficient_funds`)
`detail`	string	Yes	Safe user-facing error message
`status`	string	Yes	HTTP status code as a string
`source`	object	No	Location of the invalid request value, such as `source.pointer`
`meta`	object	Yes	Metadata containing `supportId` for troubleshooting

Metadata

Public error responses include meta.supportId by default. Internal/upstream metadata is kept in logs and traces, correlated by supportId. 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 rate_limited. The response carries a Retry-After header with the seconds to wait before retrying. See Rate limits.

Validation errors

Validation errors may include source.pointer for API clients:

{
  "errors": [
    {
      "code": "invalid_value",
      "detail": "The information you entered isn't valid. Please check it and try again.",
      "status": "422",
      "source": {
        "pointer": "/data/attributes/email"
      },
      "meta": {
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}

Cross-cutting 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.

Code	Status	Detail
`missing_instance_id`	400	X-Instance-ID is required for agent-attributed money movement. Send the X-Instance-ID header with a caller-chosen run/session identifier for this agent.
`account_closed`	403	This account has been closed. Contact support for assistance.
`account_frozen`	403	This account is temporarily frozen. Contact support for assistance.
`agent_credential_required`	403	X-Agent-ID is not accepted with a party API key or user credential. Authenticate with an agent key or an agent-scoped OAuth grant to act as an agent.
`agent_id_conflict`	403	X-Agent-ID conflicts with the agent bound to this credential. Remove the X-Agent-ID header — bound credentials carry verified agent identity.
`agent_wallet_access_no_access`	403	The agent does not have access to the selected wallet.
`delegation_required`	403	Acting on behalf of another party requires a valid delegation. To act through an agent, authenticate with that agent’s key or an agent-scoped OAuth grant.
`agent_wallet_access_wallet_required`	422	A wallet is required for this agent action.

⌘I

Overview

Agents

Customers

Payments

Transactions

Transfers

Payment Requests

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

Direct

API keys

Agent keys

Webhooks

Events

Errors

Error response format

Metadata

Rate limit errors

Validation errors

Cross-cutting errors

​Error response format

​Metadata

​Rate limit errors

​Validation errors

​Cross-cutting errors

Error response format

Metadata

Rate limit errors

Validation errors

Cross-cutting errors