> ## Documentation Index > Fetch the complete documentation index at: https://docs.natural.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python. > When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`. > When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`. > Use the Natural CLI for terminal and CI automation. > Use REST only for unsupported languages or when the user explicitly requests raw HTTP. > Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it. > For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer. > REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code. # Invite customers > Invite specific customers by email or phone to approve a set of your agents, each with its own permissions and limits ## OpenAPI ````yaml /api-reference/openapi.json post /customers/invitations openapi: 3.1.1 info: title: Natural API version: 0.2.0 description: >- Natural's payments API for autonomous agents. **Base URL:** `https://api.natural.com` AI agents, including coding agents, should prefer the hosted MCP server at `https://mcp.natural.com` when an MCP-aware host runs the agent, the Natural CLI for terminal/CI workflows, and the official SDKs for application runtimes they own. Use direct HTTP only for explicit low-level integrations, unsupported SDK gaps, or infrastructure work where REST is required. For support: support@natural.com servers: - url: https://api.natural.com description: Production security: [] tags: - name: Agents description: Agent management - name: Customers description: Customer management - name: Invitation Links description: Shareable links that offer your agents to customers - name: Payments description: Payment management - name: Payment Intents description: Accept card payments by link or voice - name: Card Payments description: Card payment attempts - name: Voice description: Collect a payment intent over a phone call - name: Refunds description: Return card payments to the payer - name: Chargebacks description: Respond to card payment chargebacks - name: Transactions description: Transaction activity and history - name: Transfers description: Deposits and withdrawals - name: PaymentRequests description: Payment request management - name: Approvals description: Approval review - name: Invitations description: Party invitation management - name: Parties description: Party and organization management - name: Wallets description: Wallet management - name: External Accounts description: Linked external bank accounts - name: External Parties description: Third parties with whom you transact over Direct - name: External Party Accounts description: Banking details belonging to external parties not on Natural - name: ACH description: Make ACH payments to external party accounts - name: Realtime description: Make realtime payments to external party accounts - name: Wire description: Send domestic wires to external party accounts - name: API Keys description: API key management - name: Agent Keys description: Agent key management - name: Card Sessions description: Let agents pay with a card without seeing the real card number - name: Agent Tokens description: Let agents spend from a mandate without seeing the real card number - name: Agent Cards description: Cards an agent requests for one purchase at one merchant - name: Card Transactions description: Purchases and refunds on Natural-issued cards - name: Webhooks description: Webhook endpoint management - name: Events description: Webhook event log - name: Simulations description: Sandbox-only simulation controls paths: /customers/invitations: post: tags: - Customers summary: Invite customers description: >- Invite specific customers by email or phone to approve a set of your agents, each with its own permissions and limits operationId: customers.createInvitations parameters: - name: X-Instance-ID in: header required: false schema: anyOf: - type: string maxLength: 1024 - type: 'null' description: >- Caller-chosen identifier for the agent run, session, or conversation, required when an agent moves money. requestBody: required: true content: application/json: schema: type: object properties: data: type: object properties: attributes: type: object properties: recipients: type: array minItems: 1 maxItems: 100 items: anyOf: - type: object properties: type: type: string enum: - email value: type: string maxLength: 254 format: email description: Email address. required: - type - value additionalProperties: false title: Email recipient - type: object properties: type: type: string enum: - phone value: type: string maxLength: 16 description: Phone number. required: - type - value additionalProperties: false title: Phone recipient - type: object properties: type: type: string enum: - party_id value: type: string pattern: ^pty_[0-9a-f]{32}$ description: Natural party ID (pty_*). required: - type - value additionalProperties: false title: Existing customer title: CustomerInvitationCreateRecipient description: >- Each recipient is one of three shapes: an email recipient (which may carry onboarding details), a phone recipient, or an existing customer referenced by party ID. agents: type: array minItems: 1 maxItems: 50 items: type: object properties: permissions: anyOf: - type: array minItems: 1 items: enum: - disputes.read - disputes.create - payments.read - payments.create - external_parties.read - external_parties.create - direct.read - direct.create - external_accounts.create - wallets.read - wallets.balance - wallets.create - wallets.update - wallets.fund - wallets.deposit - wallets.transfer - wallets.withdraw - party.read - party.update - payment_intents.create - payment_intents.read - card_payments.read - refunds.read - refunds.create - voice_sessions.read - voice_sessions.create - chargebacks.read - chargebacks.respond - mandates.read - enrollment.read - cards.read - saved_cards.use type: string title: PermissionList description: Specific permissions to request. - type: object properties: type: description: Set to `ALL`. type: string enum: - ALL required: - type additionalProperties: false title: AllPermissions description: >- Request every permission available to your party today. description: >- Permissions for this agent, or `{"type":"ALL"}` for all of them. Fixed when the invitation is created. agentId: type: string pattern: ^agt_[0-9a-f]{32}$ description: Agent ID (agt_*). limits: type: object properties: perTransaction: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' description: >- Per-transaction spending limit in cents, or null for no limit. additionalProperties: false description: Transaction limits for this agent. required: - permissions - agentId additionalProperties: false title: CustomerInvitationAgentSpec description: >- Agents to grant access to. Each recipient receives an invitation for every agent listed. expiresAt: type: string maxLength: 64 format: date-time description: >- RFC 3339 timestamp when the invitation expires. Defaults to 30 days from now; maximum 90 days. message: type: string maxLength: 180 description: >- Message stored with each recipient's invitation. It is not included in the invitation email. redirectUrl: type: string maxLength: 2048 description: >- Where to send the customer after they accept and finish setup on Natural: an https URL, an app deep link, or an sms: link. tags: type: object propertyNames: type: string minLength: 1 maxLength: 128 pattern: ^[a-zA-Z0-9_]+$ additionalProperties: type: string minLength: 1 maxLength: 256 description: Tags applied to each invitation. maxProperties: 30 required: - recipients - agents additionalProperties: false required: - attributes additionalProperties: false required: - data additionalProperties: false title: CustomerInvitationCreateRequest examples: default: summary: Default value: data: attributes: recipients: - type: email value: ops@bistroroma.com agents: - agentId: agt_019cd1798d637a4da75dce386343931d permissions: - payments.read - payments.create - external_accounts.create - wallets.balance - wallets.update - party.read - party.update limits: perTransaction: 100000 expiresAt: '2026-01-12T10:15:00.000Z' message: >- We use Natural to let our agents help manage payments for your business. redirectUrl: https://app.acmepayments.com/connected tags: campaign: q3_reactivation responses: '201': description: Successful Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: type: description: Resource type. Always `agentDelegationInvitation`. type: string enum: - agentDelegationInvitation id: type: string pattern: ^adi_[0-9a-f]{32}$ description: Invitation ID (adi_*). attributes: type: object properties: developerName: type: string description: Developer name. email: type: string description: Recipient email. phone: anyOf: - type: string - type: 'null' description: Recipient phone. url: type: string format: uri description: >- Invitation URL. Natural sends it automatically for email invitations; deliver it yourself for phone invitations. agentName: type: string description: Agent name. permissions: type: array items: type: string description: Permissions granted on accept. limits: anyOf: - type: object properties: perTransaction: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' description: >- Per-transaction spending limit in cents, or null for no limit. additionalProperties: false title: AgentLimitsSpec - type: 'null' description: Transaction limits. status: enum: - PENDING - ACCEPTED - DECLINED - EXPIRED - CANCELED type: string description: Invitation status. effectiveStatus: enum: - PENDING - ACCEPTED - DECLINED - EXPIRED - CANCELED type: string description: >- Status after applying expiry: reads EXPIRED once `expiresAt` has passed even while `status` is still PENDING. expiresAt: type: string description: RFC 3339 timestamp when the invitation expires. acceptedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the invitation was accepted, or null. declinedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the invitation was declined, or null. cancelReason: anyOf: - enum: - AGENT_RETIRED - DEVELOPER_RETIRED - DEVELOPER_REVOKED - CONNECTION_ESTABLISHED type: string - type: 'null' description: Reason for cancellation. redirectUrl: anyOf: - type: string - type: 'null' description: >- Where the customer is sent after accepting and finishing setup, or null. tags: type: object propertyNames: type: string additionalProperties: type: string description: >- Metadata visible to anyone who can read the resource. createdAt: type: string description: >- RFC 3339 timestamp when the invitation was created. updatedAt: type: string description: >- RFC 3339 timestamp when the invitation was last updated. required: - developerName - email - phone - url - agentName - permissions - limits - status - effectiveStatus - expiresAt - acceptedAt - declinedAt - cancelReason - redirectUrl - tags - createdAt - updatedAt additionalProperties: false title: AgentDelegationInvitationAttributes description: Invitation details. relationships: type: object properties: agent: type: object properties: data: type: object properties: type: description: Resource type. Always `agent`. type: string enum: - agent id: type: string pattern: ^agt_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: The invited agent. customerParty: type: object properties: data: anyOf: - type: object properties: type: description: Resource type. Always `party`. type: string enum: - party id: type: string pattern: ^pty_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: >- Customer party that accepted the invitation, or null until acceptance. required: - agent - customerParty additionalProperties: false description: Related resources. required: - type - id - attributes - relationships additionalProperties: false title: AgentDelegationInvitationResource description: Created invitations. meta: type: object properties: failedRecipients: type: array items: type: object properties: recipient: anyOf: - type: object properties: type: type: string enum: - email value: type: string maxLength: 254 format: email description: Email address. required: - type - value additionalProperties: false - type: object properties: type: type: string enum: - phone value: type: string maxLength: 16 description: Phone number. required: - type - value additionalProperties: false - type: object properties: type: type: string enum: - party_id value: type: string pattern: ^pty_[0-9a-f]{32}$ description: Natural party ID (pty_*). required: - type - value additionalProperties: false title: CustomerInvitationRecipient description: Recipient that failed. reason: type: string description: Why this recipient's invitations failed. required: - recipient - reason additionalProperties: false description: Recipients whose invitations could not be created. alreadyConnected: type: array items: type: object properties: recipient: anyOf: - type: object properties: type: type: string enum: - email value: type: string maxLength: 254 format: email description: Email address. required: - type - value additionalProperties: false - type: object properties: type: type: string enum: - phone value: type: string maxLength: 16 description: Phone number. required: - type - value additionalProperties: false - type: object properties: type: type: string enum: - party_id value: type: string pattern: ^pty_[0-9a-f]{32}$ description: Natural party ID (pty_*). required: - type - value additionalProperties: false title: CustomerInvitationRecipient description: >- Recipient whose party already has an active connection to the agent. agentId: type: string pattern: ^agt_[0-9a-f]{32}$ description: Agent that is already connected. agentDelegationId: type: string pattern: ^adl_[0-9a-f]{32}$ description: >- Existing active agent delegation that satisfied the request. required: - recipient - agentId - agentDelegationId additionalProperties: false title: AlreadyConnectedAgent description: >- Agent-recipient pairs skipped because the agent is already connected to the recipient's party. Requested permissions and limits were not applied. required: - failedRecipients - alreadyConnected additionalProperties: false description: Metadata about the batch. required: - data - meta additionalProperties: false title: CustomerInvitationCreateResponse examples: default: summary: Default value: data: - type: agentDelegationInvitation id: adi_019cd1798d96adc082e235b426d4e04c attributes: developerName: Acme Payments email: ops@bistroroma.com phone: null url: >- https://www.natural.com/connect/adi_019cd1798d96adc082e235b426d4e04c agentName: Procurement Agent permissions: - payments.read - payments.create - external_accounts.create - wallets.balance - wallets.update - party.read - party.update limits: perTransaction: 100000 status: PENDING effectiveStatus: PENDING expiresAt: '2026-01-12T10:15:00.000Z' acceptedAt: null declinedAt: null cancelReason: null redirectUrl: https://app.acmepayments.com/connected tags: campaign: q3_reactivation createdAt: '2026-01-05T10:15:00.000Z' updatedAt: '2026-01-05T10:15:00.000Z' relationships: agent: data: type: agent id: agt_019cd1798d637a4da75dce386343931d customerParty: data: null meta: failedRecipients: [] alreadyConnected: [] headers: X-RateLimit-Limit: description: Maximum requests allowed per window. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when rate limit resets. schema: type: integer '400': description: Validation Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: invalid_value detail: >- The information you entered isn't valid. Please check it and try again. status: '400' meta: supportId: req_a1b2c3d4e5f6 '401': description: Unauthorized content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: unauthenticated detail: Authentication is required. status: '401' meta: supportId: req_a1b2c3d4e5f6 '403': description: Forbidden content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: forbidden detail: You do not have permission to perform this action. status: '403' meta: supportId: req_a1b2c3d4e5f6 '404': description: >- Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing. content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: not_found detail: The requested resource was not found. status: '404' meta: supportId: req_a1b2c3d4e5f6 '409': description: Conflict content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: conflict detail: The request conflicts with the current resource state. status: '409' meta: supportId: req_a1b2c3d4e5f6 '422': description: >- Validation Error. The response contains one error object for each invalid request value. content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: invalid_value detail: 'Too big: expected string to have <=80 characters' status: '422' source: pointer: /data/attributes/description meta: supportId: req_a1b2c3d4e5f6 '428': description: Precondition Required content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: mfa_required detail: MFA verification required status: '428' meta: supportId: req_a1b2c3d4e5f6 '429': description: Too Many Requests content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: rate_limited detail: Too many requests. Please try again later. status: '429' meta: supportId: req_a1b2c3d4e5f6 headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer X-RateLimit-Limit: description: Maximum requests allowed per window. schema: type: integer X-RateLimit-Remaining: description: Requests remaining in current window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when rate limit resets. schema: type: integer '500': description: Internal Server Error content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: server_error detail: Something went wrong. status: '500' meta: supportId: req_a1b2c3d4e5f6 '501': description: Not Implemented content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: not_implemented detail: This operation is not available. status: '501' meta: supportId: req_a1b2c3d4e5f6 '502': description: Bad Gateway content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: bad_gateway detail: >- We couldn't complete that request because one of Natural's services returned an unexpected response. Please try again. status: '502' meta: supportId: req_a1b2c3d4e5f6 '503': description: Service Unavailable content: application/json: schema: type: object properties: errors: type: array minItems: 1 items: type: object properties: code: type: string description: Stable lower-snake-case public error code. detail: type: string description: Safe user-facing error detail. status: type: string description: HTTP status code as a string. source: type: object description: Location of the invalid request value. properties: pointer: type: string description: JSON Pointer to the invalid request value. parameter: type: string description: Name of the invalid query parameter. header: type: string description: Name of the invalid request header. additionalProperties: false meta: type: object description: >- Additional error context, including support and provider details when available. properties: supportId: type: string description: Request/support ID for troubleshooting. limitScope: type: string enum: - merchant - program description: >- Which family of acquiring limit refused the payment. Thresholds and usage are never disclosed. connectionStatus: type: string enum: - login_required - disconnected description: >- External account connection state when the error is repairable by relinking. provider: type: object description: Provider error details, when available. properties: name: type: string enum: - plaid description: Provider that returned the underlying error. errorCode: type: string description: Provider error code, when available. errorType: type: string description: Provider error type, when available. requestId: type: string description: Provider request ID for troubleshooting. required: - name additionalProperties: false required: - supportId additionalProperties: false required: - code - detail - status - meta additionalProperties: false required: - errors additionalProperties: false examples: default: summary: Default value: errors: - code: service_unavailable detail: The service is temporarily unavailable. status: '503' meta: supportId: req_a1b2c3d4e5f6 security: - HTTPBearer: [] components: securitySchemes: HTTPBearer: type: http scheme: bearer description: >- Bearer authentication: send your API key, agent key, or OAuth access token as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.