> ## 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. # List approvals > List approvals ## OpenAPI ````yaml /api-reference/openapi.json get /approvals 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: /approvals: get: tags: - Approvals summary: List approvals description: List approvals operationId: approvals.list parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum results per page. allowEmptyValue: true allowReserved: true - name: status in: query schema: enum: - pending - approved - denied - canceled type: string description: Filter by status. Defaults to pending. allowEmptyValue: true allowReserved: true - name: cursor in: query schema: type: string maxLength: 1024 description: Cursor from the previous page. allowEmptyValue: true allowReserved: true - 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. responses: '200': description: Successful Response content: application/json: schema: type: object properties: data: type: array items: type: object properties: type: description: Resource type. Always `approval`. type: string enum: - approval id: type: string description: Approval ID (apr_*). attributes: type: object properties: status: enum: - pending - approved - denied - canceled type: string description: Approval status. target: type: object properties: type: enum: - payment - paymentRequest - deposit - withdrawal - ach - realtime - wire - check type: string description: Type of operation under approval. id: type: string description: >- Public ID of the operation under approval. Legacy payment-request approvals reference the parent payment request (prq_), never an internal fulfillment. required: - type - id additionalProperties: false description: Operation that needs approval. payment: anyOf: - type: object properties: amount: type: integer description: Amount in cents. currency: type: string description: Currency code. required: - amount - currency additionalProperties: false - type: 'null' description: >- Amount of the operation under review. Null when the underlying amount is unavailable. fee: anyOf: - type: object properties: amount: type: integer exclusiveMinimum: 0 description: Fee amount in cents. currency: enum: - USD type: string description: Currency of the fee. payer: description: Party role charged the fee. type: string enum: - sender applied: description: >- The fee is added to the sender's cost without reducing the principal amount. type: string enum: - on_top required: - amount - currency - payer - applied additionalProperties: false title: SenderOnTopFee - type: 'null' description: >- Fee the sender pays on top of `payment.amount`. Before the operation is submitted, including just after approval, a quote at the price in effect when it was created. After, the same fee the operation's own resource reports. Null when no fee applies, including denied or canceled approvals, operations that ended before submission, and operations whose own resource hides the fee. Also null when Billing can't quote the fee at read time; the fee still applies when the operation is submitted. reasons: type: array items: anyOf: - type: object properties: type: description: Reason type. Always `limitExceeded`. type: string enum: - limitExceeded limitType: enum: - perTransactionAmount - dailyAmount - monthlyAmount type: string description: Type of limit that was exceeded. limitAmount: type: integer description: Configured limit amount in cents. actualAmount: type: integer description: >- Amount that exceeded the limit, in cents. currency: type: string description: Currency code. required: - type - limitType - limitAmount - actualAmount - currency additionalProperties: false description: Reasons this approval is under review. customer: anyOf: - type: object properties: id: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Customer party (pty_*) whose wallet a delegated payment spends from. name: anyOf: - type: string - type: 'null' description: >- Display name of the customer party, or null when unresolved. required: - id - name additionalProperties: false - type: 'null' description: >- Customer the agent is spending on behalf of, or null when the approval isn't a delegated payment. ach: anyOf: - type: object properties: direction: enum: - credit type: string description: Direction of the payment. secCode: enum: - WEB - PPD - TEL - CCD type: string description: >- ACH SEC code the entry is submitted under. companyEntryDescription: type: string description: >- Company entry description submitted on the ACH entry. addenda: anyOf: - type: string - type: 'null' description: >- Payment-related information submitted as the NACHA addenda record, or null. internalDescription: anyOf: - type: string - type: 'null' description: >- Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network. companyName: type: string description: Company name submitted on the ACH entry. expectedAvailableAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the funds are expected to be available, or null when unknown. counterparty: anyOf: - type: object properties: externalPartyId: type: string pattern: ^epty_[0-9a-f]{32}$ description: External party being paid (epty_*). name: type: string description: External party display or legal name. kind: enum: - individual - business type: string description: External party type. account: type: object properties: id: type: string pattern: ^epa_[0-9a-f]{32}$ description: External party account (epa_*). accountType: enum: - checking - savings type: string description: Bank account type. last4: type: string minLength: 4 maxLength: 4 description: Last four account number digits. mask: type: string description: Masked account number. required: - id - accountType - last4 - mask additionalProperties: false description: >- Masked bank account the ACH payment uses. required: - externalPartyId - name - kind - account additionalProperties: false title: ApprovalAchCounterparty - type: 'null' description: >- Counterparty and masked account, or null when it can no longer be resolved. required: - direction - secCode - companyEntryDescription - addenda - internalDescription - companyName - expectedAvailableAt - counterparty additionalProperties: true title: ApprovalAch - type: 'null' description: >- ACH-specific review context. Null unless the target is an ACH. wire: anyOf: - type: object properties: description: type: string description: >- Description supplied when the wire was created. remittanceInfo: anyOf: - type: string - type: 'null' description: Remittance information, or null. internalDescription: anyOf: - type: string - type: 'null' description: >- Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network. counterparty: anyOf: - type: object properties: externalPartyId: type: string pattern: ^epty_[0-9a-f]{32}$ description: External party being paid (epty_*). name: type: string description: External party display or legal name. kind: enum: - individual - business type: string description: External party type. account: type: object properties: id: type: string pattern: ^epa_[0-9a-f]{32}$ description: External party account (epa_*). accountType: enum: - checking - savings type: string description: Bank account type. last4: type: string minLength: 4 maxLength: 4 description: Last four account number digits. mask: type: string description: Masked account number. required: - id - accountType - last4 - mask additionalProperties: false description: Masked bank account the payment credits. required: - externalPartyId - name - kind - account additionalProperties: false title: ApprovalRealtimeCounterparty - type: 'null' description: >- Destination party and masked account, or null when it can no longer be resolved. required: - description - remittanceInfo - internalDescription - counterparty additionalProperties: false title: ApprovalWire - type: 'null' description: >- Wire-specific review context. Null unless the target is a wire. check: anyOf: - type: object properties: payeeName: type: string description: Name printed on the check. payeeCity: type: string description: Payee mailing address city. payeeState: type: string description: Payee mailing address state. amount: type: integer description: Check amount in cents. memo: type: string description: Memo printed on the check. internalDescription: anyOf: - type: string - type: 'null' description: >- Description for the sender's internal reference, or null. Never printed on the check or shared with the counterparty. required: - payeeName - payeeCity - payeeState - amount - memo - internalDescription additionalProperties: false title: ApprovalCheck - type: 'null' description: >- Check-specific review context. Null unless the target is a check. realtime: anyOf: - type: object properties: description: type: string description: >- Description supplied when the payment was created. internalDescription: anyOf: - type: string - type: 'null' description: >- Description for the sender's internal reference, or null. Never shared with the counterparty or the banking network. counterparty: anyOf: - type: object properties: externalPartyId: type: string pattern: ^epty_[0-9a-f]{32}$ description: External party being paid (epty_*). name: type: string description: External party display or legal name. kind: enum: - individual - business type: string description: External party type. account: type: object properties: id: type: string pattern: ^epa_[0-9a-f]{32}$ description: External party account (epa_*). accountType: enum: - checking - savings type: string description: Bank account type. last4: type: string minLength: 4 maxLength: 4 description: Last four account number digits. mask: type: string description: Masked account number. required: - id - accountType - last4 - mask additionalProperties: false description: Masked bank account the payment credits. required: - externalPartyId - name - kind - account additionalProperties: false title: ApprovalRealtimeCounterparty - type: 'null' description: >- Destination party and masked account, or null when it can no longer be resolved. required: - description - internalDescription - counterparty additionalProperties: false title: ApprovalRealtime - type: 'null' description: >- Realtime-specific review context. Null unless the target is a realtime payment. denialReason: anyOf: - type: string - type: 'null' description: >- Reason recorded when the approval was denied, when one was given. createdAt: type: string description: >- RFC 3339 timestamp when the approval was created. updatedAt: type: string description: >- RFC 3339 timestamp when the approval was last updated. resolvedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the approval was resolved, or null while pending. required: - status - target - payment - fee - reasons - customer - ach - wire - check - realtime - denialReason - createdAt - updatedAt - resolvedAt additionalProperties: false relationships: type: object properties: initiatorAgent: type: object properties: data: anyOf: - 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. - type: 'null' required: - data additionalProperties: false description: >- Agent that initiated this resource, or null when no agent can be reliably attributed. required: - initiatorAgent additionalProperties: false required: - type - id - attributes - relationships additionalProperties: false meta: type: object properties: pagination: type: object properties: hasMore: type: boolean description: Whether more results are available. nextCursor: anyOf: - type: string - type: 'null' description: >- Cursor for the next page, or null when there are no more results. required: - hasMore - nextCursor additionalProperties: false title: PaginationMeta required: - pagination additionalProperties: false required: - data - meta additionalProperties: false examples: default: summary: Default value: data: - relationships: initiatorAgent: data: type: agent id: agt_019cd1798d637a4da75dce386343931d type: approval id: apr_019cd1798d8a74dd75c16fc6d843db81 attributes: status: pending target: type: payment id: pay_019cd1798d794c2f2ccf31b4e8394f2d payment: amount: 500000 currency: USD fee: amount: 100 currency: USD payer: sender applied: on_top reasons: - type: limitExceeded limitType: perTransactionAmount limitAmount: 250000 actualAmount: 500000 currency: USD customer: null ach: null realtime: null wire: null check: null denialReason: null createdAt: '2026-01-04T15:30:00.000Z' updatedAt: '2026-01-04T15:30:00.000Z' resolvedAt: null meta: pagination: hasMore: false nextCursor: null 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.