> ## 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 searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`. > Use the Natural CLI for terminal and CI automation. > 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 check payments > List your check payments ## OpenAPI ````yaml /api-reference/openapi.json get /check 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: Check description: Mail paper checks to external parties - 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: Webhooks description: Webhook endpoint management - name: Events description: Webhook event log - name: Simulations description: Sandbox-only simulation controls paths: /check: get: tags: - Check summary: List check payments description: List your check payments operationId: check.list parameters: - name: customerPartyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Customer party to act for (pty_*). Omit to act as your own party. To act for another party, pass the ID of a party that has authorized you to act on its behalf. allowEmptyValue: true allowReserved: true - name: status in: query schema: enum: - CREATED - AWAITING_APPROVAL - APPROVAL_DENIED - PROCESSING - COMPLETED - RETURNED - CANCELING - CANCELED - EXPIRED - REJECTED - FAILED type: string description: Filter by status. allowEmptyValue: true allowReserved: true - name: externalPartyId in: query schema: type: string pattern: ^epty_[0-9a-f]{32}$ description: Only checks to this external party (epty_*). allowEmptyValue: true allowReserved: true - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum results per page. 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 `check`. type: string enum: - check id: type: string pattern: ^chk_[0-9a-f]{32}$ description: Check ID (chk_*). attributes: type: object properties: amount: type: integer exclusiveMinimum: 0 description: Amount in cents. currency: description: Currency code. type: string enum: - USD status: enum: - CREATED - AWAITING_APPROVAL - APPROVAL_DENIED - PROCESSING - COMPLETED - RETURNED - CANCELING - CANCELED - EXPIRED - REJECTED - FAILED type: string description: >- Check status, in lifecycle order: CREATED, AWAITING_APPROVAL, PROCESSING, COMPLETED; APPROVAL_DENIED, RETURNED, CANCELING, CANCELED, EXPIRED, REJECTED, or FAILED end it. memo: type: string description: Memo printed on the check. message: anyOf: - type: string - type: 'null' description: Message printed on the check, or null. internalDescription: anyOf: - type: string - type: 'null' description: >- Description for your internal reference, or null. Never printed on the check or shared with the counterparty. deliveryMethod: enum: - USPS_FIRST_CLASS - FEDEX_TWO_DAY - FEDEX_OVERNIGHT type: string description: How the check is mailed. checkNumber: anyOf: - type: string - type: 'null' description: Printed check number, or null. voidDate: anyOf: - type: string - type: 'null' description: Date after which the check is void, or null. payee: type: object properties: name: type: string description: Payee name printed on the check. line1: type: string description: Payee street address line 1. line2: anyOf: - type: string - type: 'null' description: Payee street address line 2. city: type: string description: Payee city. state: type: string description: Payee state. postalCode: type: string description: Payee postal code. addressVersion: type: integer description: >- Version of the recipient address captured when the check was created. required: - name - line1 - line2 - city - state - postalCode - addressVersion additionalProperties: false title: CheckPayee description: >- Payee and the address the check was mailed to, captured when the check was created. delivery: anyOf: - type: object properties: status: enum: - CREATED - RENDERED_PDF - MAILED - IN_TRANSIT - IN_LOCAL_AREA - PROCESSED_FOR_DELIVERY - DELIVERED - REROUTED - RETURNED_TO_SENDER - FAILED type: string description: USPS delivery status. trackingUrl: anyOf: - type: string - type: 'null' description: >- Tracking URL for the mailed check, or null. mailedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was mailed, or null. deliveredAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was delivered, or null. returnedToSenderAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was returned to sender, or null. updatedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when delivery was last updated, or null. required: - status - trackingUrl - mailedAt - deliveredAt - returnedToSenderAt - updatedAt additionalProperties: false - type: 'null' description: >- Delivery tracking for the mailed check, or null before it is rendered. presentmentReturns: type: array items: type: object properties: code: type: string description: Presentment return code. reason: type: string description: Presentment return reason. observedAt: type: string description: >- RFC 3339 timestamp when the presentment return was observed. required: - code - reason - observedAt additionalProperties: false title: CheckPresentmentReturn description: >- Presentment returns observed without moving the payment status. return: anyOf: - type: object properties: code: type: string description: Return code. reason: anyOf: - type: string - type: 'null' description: Return reason, or null. observedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the return was observed, or null. required: - code - reason - observedAt additionalProperties: false - type: 'null' description: Post-settlement return details, or null. cancellation: anyOf: - type: object properties: reason: anyOf: - type: string - type: 'null' description: Cancellation reason, or null. returnCode: anyOf: - type: string - type: 'null' description: >- Return code that drove the cancellation, or null. requestedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when cancellation was requested, or null. confirmedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when cancellation was confirmed, or null. required: - reason - returnCode - requestedAt - confirmedAt additionalProperties: false - type: 'null' description: >- Cancellation details when the check is canceling or canceled, or null. failure: anyOf: - type: object properties: code: anyOf: - type: string - type: 'null' description: Failure code, or null. reason: anyOf: - type: string - type: 'null' description: Failure reason, or null. required: - code - reason additionalProperties: false - type: 'null' description: Failure details when the check failed, or null. canonicalReason: anyOf: - type: string - type: 'null' description: Canonical terminal reason, or null. submittedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was submitted, or null. issuedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was issued, or null. stopRequestedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when a stop was requested, or null. completedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check completed, or null. returnedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was returned, or null. canceledAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was canceled, or null. expiredAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check expired, or null. rejectedAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check was rejected, or null. terminalAt: anyOf: - type: string - type: 'null' description: >- RFC 3339 timestamp when the check reached a terminal status, or null. createdAt: type: string description: RFC 3339 timestamp when the check was created. updatedAt: type: string description: >- RFC 3339 timestamp when the check was last updated. required: - amount - currency - status - memo - message - internalDescription - deliveryMethod - checkNumber - voidDate - payee - delivery - presentmentReturns - return - cancellation - failure - canonicalReason - submittedAt - issuedAt - stopRequestedAt - completedAt - returnedAt - canceledAt - expiredAt - rejectedAt - terminalAt - createdAt - updatedAt additionalProperties: false title: CheckAttributes relationships: type: object properties: customerParty: type: object properties: data: 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. required: - data additionalProperties: false title: ToOneRelationship description: Party the check was created for. wallet: type: object properties: data: type: object properties: type: description: Resource type. Always `wallet`. type: string enum: - wallet id: type: string pattern: ^wal_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: Wallet the check pays from. externalParty: type: object properties: data: type: object properties: type: description: Resource type. Always `external_party`. type: string enum: - external_party id: type: string pattern: ^epty_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: External party paid. required: - customerParty - wallet - externalParty additionalProperties: false title: CheckRelationships required: - type - id - attributes - relationships additionalProperties: false title: CheckResource 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: - type: check id: chk_019cd1798d875d7c0a4165d10dc4db29 attributes: amount: 25000 currency: USD status: COMPLETED memo: Invoice 1042 message: Thank you for your business internalDescription: Q3 vendor true-up deliveryMethod: USPS_FIRST_CLASS checkNumber: '1042' voidDate: '2027-03-02' payee: name: Acme Supply LLC line1: 1200 Broadway line2: Suite 400 city: Oakland state: CA postalCode: '94612' addressVersion: 3 delivery: status: DELIVERED trackingUrl: null mailedAt: '2026-09-03T15:30:05.000Z' deliveredAt: '2026-09-08T18:10:00.000Z' returnedToSenderAt: null updatedAt: '2026-09-08T18:10:00.000Z' presentmentReturns: [] return: null cancellation: null failure: null canonicalReason: null submittedAt: '2026-09-03T15:30:05.000Z' issuedAt: '2026-09-03T15:30:05.000Z' stopRequestedAt: null completedAt: '2026-09-10T14:00:00.000Z' returnedAt: null canceledAt: null expiredAt: null rejectedAt: null terminalAt: '2026-09-10T14:00:00.000Z' createdAt: '2026-09-03T15:30:00.000Z' updatedAt: '2026-09-10T14:00:00.000Z' relationships: customerParty: data: type: party id: pty_019cd1798d617f65a79cb965dda9eac3 wallet: data: type: wallet id: wal_019cd1798d714ce765e0486a417c23dc externalParty: data: type: external_party id: epty_019cd1798d8d6873421613705e3c1415 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.