> ## 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 card transactions > List purchases and refunds on Natural-issued cards, newest first. An agent sees only its own card transactions. ## OpenAPI ````yaml /api-reference/openapi-early-access.json get /card-transactions openapi: 3.1.1 info: title: Natural API (early access) version: 0.2.0 description: |- Early-access endpoints of Natural's payments API. **Base URL:** `https://api.natural.com` For access: hi@natural.com servers: - url: https://api.natural.com description: Production security: [] tags: - name: Payment attachments description: Private supporting documents for payments - name: Subscriptions description: Subscriptions and installments paid by card - 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: Simulations description: Sandbox-only simulation controls paths: /card-transactions: get: tags: - Card Transactions summary: List card transactions description: >- List purchases and refunds on Natural-issued cards, newest first. An agent sees only its own card transactions. operationId: cardTransactions.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: cursor in: query schema: type: string maxLength: 1024 description: Cursor from the previous page. allowEmptyValue: true allowReserved: true - name: walletId in: query schema: type: string pattern: ^wal_[0-9a-f]{32}$ description: Only card transactions on this wallet (wal_*). allowEmptyValue: true allowReserved: true - name: cardId in: query schema: type: string pattern: ^pcd_[0-9a-f]{32}$ description: Only card transactions on this card (pcd_*). allowEmptyValue: true allowReserved: true - name: agentId in: query schema: type: string pattern: ^agt_[0-9a-f]{32}$ description: Only card transactions this agent made (agt_*). allowEmptyValue: true allowReserved: true - name: status in: query schema: enum: - pending - authorized - partially_captured - captured - reversed - declined - refunded type: string description: Only card transactions in this status. allowEmptyValue: true allowReserved: true - name: createdAfter in: query schema: type: string maxLength: 64 pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$ description: >- Only card transactions that happened after this RFC 3339 timestamp. allowEmptyValue: true allowReserved: true - name: createdBefore in: query schema: type: string maxLength: 64 pattern: >- ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$ description: >- Only card transactions that happened before this RFC 3339 timestamp. allowEmptyValue: true allowReserved: true - name: customerPartyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: >- Customer party to act for (pty_*). Omit to read your own party's card transactions. To read a connected customer's, pass its ID; you need the customer's cards.read grant. 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 `cardTransaction`. type: string enum: - cardTransaction id: type: string pattern: ^cit_[0-9a-f]{32}$ description: Card transaction ID (cit_*). attributes: type: object properties: kind: enum: - purchase - refund type: string description: >- purchase: money paid to a merchant. refund: money a merchant returned. status: enum: - pending - authorized - partially_captured - captured - reversed - declined - refunded type: string description: >- pending: a refund the merchant approved that hasn't settled. authorized: a purchase holds money. partially_captured: part of the hold was spent and part is still held or released. captured: the purchase settled. reversed: the hold was released and nothing was spent. declined: the card declined it. refunded: the refund settled. merchant: type: object properties: name: type: string description: Merchant name as the card network sent it. categoryCode: anyOf: - type: string - type: 'null' description: >- Merchant category code (MCC), when the network sent one. city: anyOf: - type: string - type: 'null' description: Merchant city, when the network sent one. country: anyOf: - type: string - type: 'null' description: >- Merchant country as an ISO 3166-1 alpha-2 code, when known. required: - name - categoryCode - city - country additionalProperties: false title: CardTransactionMerchant amounts: type: object properties: attempted: type: integer description: Amount the merchant asked for, in cents. authorized: type: integer description: Amount the card approved, in cents. captured: type: integer description: Amount spent, in cents. released: type: integer description: >- Amount of the hold given back unspent, in cents. refunded: type: integer description: Amount refunded and settled, in cents. outstandingHold: type: integer description: Amount still held on the wallet, in cents. required: - attempted - authorized - captured - released - refunded - outstandingHold additionalProperties: false title: CardTransactionAmounts description: >- Each amount is a separate fact. Zero means that fact hasn't moved money. currency: description: Currency code. Only USD is supported. type: string enum: - USD decline: anyOf: - type: object properties: code: type: string description: >- Stable decline code, such as insufficient_funds. message: type: string description: >- A plain-language explanation of the decline. required: - code - message additionalProperties: false title: CardTransactionDecline - type: 'null' description: Why the card declined it, or null. actor: anyOf: - type: object properties: type: type: string enum: - person userId: type: string pattern: ^usr_[0-9a-f]{32}$ description: The person who used the card (usr_*). required: - type - userId additionalProperties: false title: CardTransactionPersonActor - type: object properties: type: type: string enum: - agent agentId: type: string pattern: ^agt_[0-9a-f]{32}$ description: The agent that used the card (agt_*). agentDelegationId: anyOf: - type: string pattern: ^adl_[0-9a-f]{32}$ - type: 'null' description: >- The connection the agent acted through (adl_*), when a connected agent used the card for a customer. Null for your own agent. required: - type - agentId - agentDelegationId additionalProperties: false title: CardTransactionAgentActor title: CardTransactionActor description: Who used the card. timeline: type: array items: type: object properties: kind: enum: - attempted - authorized - declined - captured - released - reversed - refunded type: string description: What happened. occurredAt: type: string description: RFC 3339 timestamp when it happened. amount: type: integer description: Amount of this event, in cents. decline: anyOf: - type: object properties: code: type: string description: >- Stable decline code, such as insufficient_funds. message: type: string description: >- A plain-language explanation of the decline. required: - code - message additionalProperties: false title: CardTransactionDecline - type: 'null' description: Why it declined, on a declined event. required: - kind - occurredAt - amount - decline additionalProperties: false title: CardTransactionTimelineEvent description: >- Every event on this card transaction, oldest first. occurredAt: type: string description: RFC 3339 timestamp when the card was first used. updatedAt: type: string description: >- RFC 3339 timestamp when Natural last recorded a change. required: - kind - status - merchant - amounts - currency - decline - actor - timeline - occurredAt - updatedAt additionalProperties: false title: CardTransactionAttributes relationships: type: object properties: card: type: object properties: data: type: object properties: type: description: Resource type. Always `card`. type: string enum: - card id: type: string pattern: ^pcd_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: >- The card used (pcd_*). Card numbers are never returned. 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 card draws on. transaction: type: object properties: data: type: object properties: type: description: Resource type. Always `transaction`. type: string enum: - transaction id: type: string pattern: ^txn_[0-9a-f]{32}$ description: Transaction ID (txn_*). required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship description: The same activity in GET /transactions. purchase: type: object properties: data: anyOf: - type: object properties: type: description: Resource type. Always `cardTransaction`. type: string enum: - cardTransaction id: type: string pattern: ^cit_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. - type: 'null' required: - data additionalProperties: false title: NullableToOneRelationship description: >- For a refund, the purchase it returns money for, when known. Null on a purchase. refunds: type: object properties: data: type: array items: type: object properties: type: description: Resource type. Always `cardTransaction`. type: string enum: - cardTransaction id: type: string pattern: ^cit_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToManyRelationship description: For a purchase, its refunds. Empty on a refund. required: - card - wallet - transaction - purchase - refunds additionalProperties: false title: CardTransactionRelationships required: - type - id - attributes - relationships additionalProperties: false title: CardTransactionResource 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 title: CardTransactionListResponse examples: default: summary: Default value: data: - type: cardTransaction id: cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f22 attributes: kind: refund status: pending merchant: name: BLUE BOTTLE COFFEE categoryCode: '5814' city: Oakland country: US amounts: attempted: 1200 authorized: 1200 captured: 0 released: 0 refunded: 0 outstandingHold: 0 currency: USD decline: null actor: type: agent agentId: agt_01a0e6466ba3713bba0f0d9d36803b93 agentDelegationId: null timeline: - kind: authorized occurredAt: '2026-10-06T15:30:00.000Z' amount: 1200 decline: null occurredAt: '2026-10-06T15:30:00.000Z' updatedAt: '2026-10-06T15:30:02.000Z' relationships: card: data: type: card id: pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21 wallet: data: type: wallet id: wal_01a0e6466ba3713bba0f0d9d36803b92 transaction: data: type: transaction id: txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f22 purchase: data: type: cardTransaction id: cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21 refunds: data: [] - type: cardTransaction id: cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21 attributes: kind: purchase status: captured merchant: name: BLUE BOTTLE COFFEE categoryCode: '5814' city: Oakland country: US amounts: attempted: 4250 authorized: 4250 captured: 4250 released: 0 refunded: 0 outstandingHold: 0 currency: USD decline: null actor: type: agent agentId: agt_01a0e6466ba3713bba0f0d9d36803b93 agentDelegationId: null timeline: - kind: authorized occurredAt: '2026-10-05T18:01:00.000Z' amount: 4250 decline: null - kind: captured occurredAt: '2026-10-06T09:12:00.000Z' amount: 4250 decline: null occurredAt: '2026-10-05T18:01:00.000Z' updatedAt: '2026-10-06T09:12:03.000Z' relationships: card: data: type: card id: pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21 wallet: data: type: wallet id: wal_01a0e6466ba3713bba0f0d9d36803b92 transaction: data: type: transaction id: txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21 purchase: data: null refunds: data: - type: cardTransaction id: cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f22 - type: cardTransaction id: cit_01a0e6a1d4c27b1a9f3e5d7c8b6a4f23 attributes: kind: purchase status: declined merchant: name: BLUE BOTTLE COFFEE categoryCode: '5814' city: Oakland country: US amounts: attempted: 9900 authorized: 0 captured: 0 released: 0 refunded: 0 outstandingHold: 0 currency: USD decline: code: single_use_amount_over_maximum message: The purchase was over the agent card's maximum. actor: type: agent agentId: agt_01a0e6466ba3713bba0f0d9d36803b93 agentDelegationId: null timeline: - kind: declined occurredAt: '2026-10-05T17:58:00.000Z' amount: 9900 decline: code: single_use_amount_over_maximum message: >- The purchase was over the agent card's maximum. occurredAt: '2026-10-05T17:58:00.000Z' updatedAt: '2026-10-05T17:58:01.000Z' relationships: card: data: type: card id: pcd_01a0e6a1d4c27b1a9f3e5d7c8b6a4f21 wallet: data: type: wallet id: wal_01a0e6466ba3713bba0f0d9d36803b92 transaction: data: type: transaction id: txn_01a0e6a1d4c27b1a9f3e5d7c8b6a4f23 purchase: data: null refunds: data: [] 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.