> ## 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 chargebacks > List chargebacks on card payments received by the customer ## OpenAPI ````yaml /api-reference/openapi.json get /chargebacks 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: 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: Webhooks description: Webhook endpoint management - name: Events description: Webhook event log - name: Simulations description: Sandbox-only simulation controls paths: /chargebacks: get: tags: - Chargebacks summary: List chargebacks description: List chargebacks on card payments received by the customer operationId: chargebacks.list parameters: - name: customerPartyId in: query schema: type: string pattern: ^pty_[0-9a-f]{32}$ description: Connected customer to act on behalf of. allowEmptyValue: true allowReserved: true - name: cardPaymentId in: query schema: type: string pattern: ^cpy_[0-9a-f]{32}$ allowEmptyValue: true allowReserved: true - name: paymentIntentId in: query schema: type: string pattern: ^pmi_[0-9a-f]{32}$ allowEmptyValue: true allowReserved: true - name: status in: query schema: enum: - needsResponse - expired - accepted - submitted - underReview - won - lost type: string allowEmptyValue: true allowReserved: true - name: limit in: query schema: type: integer minimum: 1 maximum: 25 default: 10 allowEmptyValue: true allowReserved: true - name: cursor in: query schema: type: string maxLength: 1024 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: id: type: string pattern: ^cbk_[0-9a-f]{32}$ type: type: string enum: - chargeback attributes: type: object properties: amount: type: integer minimum: 0 description: Disputed amount in the currency's smallest unit. currency: type: string description: >- Reported ISO 4217 currency of the disputed amount. status: enum: - needsResponse - expired - accepted - submitted - underReview - won - lost type: string description: >- Response and outcome state. Submitted means Natural accepted the response. Under review requires provider acknowledgment. Accepted and expired are not provider-reported losses. network: enum: - visa - mastercard - discover - unknown type: string description: Card network that reported the case. reason: type: object properties: category: enum: - fraud - authorization - processingError - duplicate - notReceived - unacceptableOrCanceled - creditNotProcessed - unknown type: string networkCode: type: string description: >- Network reason code, interpreted with the network. description: anyOf: - type: string - type: 'null' description: >- Readable reason description, or null when unavailable. required: - category - networkCode - description additionalProperties: false responseDueAt: type: string format: date-time description: >- Enforced deadline for accepting or responding to this chargeback. internalDueAt: type: string format: date-time description: >- Earlier merchant-facing deadline. Respond before this time so Natural can deliver the response before the enforced deadline. paymentCreatedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When the disputed payment was made, or null when unavailable. submittedAt: anyOf: - type: string format: date-time - type: 'null' description: >- When Natural accepted and froze the response. This does not establish provider acknowledgment. allowedActions: type: array items: enum: - accept - counter type: string description: >- Actions still available to the merchant, computed server-side. counterUnavailableReason: anyOf: - enum: - deadlinePassed type: string - type: 'null' description: >- Why countering is unavailable, or null when it is available or not applicable. evidence: type: object properties: responseReason: anyOf: - enum: - cardholderWithdrew - authorizedPurchase - alreadyRefunded - receivedProduct - other type: string - type: 'null' description: Why you are contesting the chargeback. product: anyOf: - anyOf: - type: object properties: type: type: string enum: - physical shipTo: anyOf: - type: object properties: line1: type: string maxLength: 255 line2: anyOf: - type: string maxLength: 255 - type: 'null' city: type: string maxLength: 255 state: type: string maxLength: 255 postalCode: type: string maxLength: 32 country: type: string pattern: ^[A-Za-z]{2}$ required: - line1 - line2 - city - state - postalCode - country additionalProperties: false - type: 'null' carrier: anyOf: - type: string maxLength: 100 - type: 'null' trackingNumber: anyOf: - type: string maxLength: 100 - type: 'null' shippedOn: anyOf: - type: string format: date - type: 'null' required: - type - shipTo - carrier - trackingNumber - shippedOn additionalProperties: false - type: object properties: type: type: string enum: - digital accessActivityLog: anyOf: - type: string maxLength: 5000 - type: 'null' required: - type - accessActivityLog additionalProperties: false - type: object properties: type: type: string enum: - inPersonService serviceOn: anyOf: - type: string format: date - type: 'null' required: - type - serviceOn additionalProperties: false - type: object properties: type: type: string enum: - other required: - type additionalProperties: false title: ChargebackEvidenceProduct - type: 'null' description: >- Product type and fulfillment details. A supplied object replaces the whole product. productDescription: anyOf: - type: string - type: 'null' description: Description of the goods or services sold. explanation: anyOf: - type: string - type: 'null' description: >- Explanation of why the chargeback should be reversed. deliveryDetails: anyOf: - type: string - type: 'null' description: How the goods or services were delivered. usageDetails: anyOf: - type: string - type: 'null' description: >- How the cardholder received or used the purchase. cardholderName: anyOf: - type: string - type: 'null' description: Cardholder name supplied by the customer. cardholderEmail: anyOf: - type: string - type: 'null' description: Cardholder email supplied by the customer. cardholderPhone: anyOf: - type: string - type: 'null' description: Cardholder phone supplied by the customer. billingAddress: anyOf: - type: string - type: 'null' description: Billing address supplied by the customer. billingPostalCode: anyOf: - type: string - type: 'null' description: >- Billing postal code supplied by the customer. refundPolicyDisclosure: anyOf: - type: string - type: 'null' description: >- How and when the refund policy was disclosed. refundDetails: anyOf: - type: string - type: 'null' description: Additional explanation of a relevant refund. attachments: type: array items: type: object properties: fileId: type: string pattern: ^evf_[0-9a-f]{32}$ description: >- ID of a validated file uploaded for this chargeback. purposes: type: array minItems: 1 maxItems: 15 items: enum: - cardholderCommunications - receipt - authorizationProof - duplicatePaymentReceipt - fulfillmentProof - trackingDocumentation - accessConfirmation - serviceCompletion - productDescription - cancellationPolicy - refundProof - refundPolicy - disputeWithdrawal - supportingDocuments - otherEvidence type: string note: anyOf: - type: string - type: 'null' file: type: object properties: filename: anyOf: - type: string - type: 'null' description: >- Sanitized filename. Null for files uploaded before filename capture was available. contentType: enum: - application/pdf - image/jpeg - image/png type: string sizeBytes: anyOf: - type: integer exclusiveMinimum: 0 - type: 'null' description: >- Original uploaded bytes. Null for historical files whose original size was not recorded. pageCount: type: integer exclusiveMinimum: 0 description: >- Number of pages this file contributes to the evidence packet. createdAt: type: string format: date-time description: >- When the file was uploaded and validated. required: - filename - contentType - sizeBytes - pageCount - createdAt additionalProperties: false required: - fileId - purposes - note - file additionalProperties: false required: - responseReason - product - productDescription - explanation - deliveryDetails - usageDetails - cardholderName - cardholderEmail - cardholderPhone - billingAddress - billingPostalCode - refundPolicyDisclosure - refundDetails - attachments additionalProperties: false title: ChargebackEvidence evidenceGuidance: type: object properties: responseReasons: type: array items: type: object properties: value: enum: - cardholderWithdrew - authorizedPurchase - alreadyRefunded - receivedProduct - other type: string description: type: string warning: anyOf: - type: string - type: 'null' required: - value - description - warning additionalProperties: false information: type: array items: type: object properties: field: enum: - cardholderName - cardholderEmail - cardholderPhone - billingAddress - billingPostalCode type: string value: anyOf: - type: string - type: 'null' source: enum: - recorded - provided - missing type: string required: - field - value - source additionalProperties: false missingFields: type: array items: type: object properties: field: enum: - responseReason - product - productDescription - explanation type: string description: type: string required: - field - description additionalProperties: false recommendedDocuments: type: array items: type: object properties: purpose: enum: - cardholderCommunications - receipt - authorizationProof - duplicatePaymentReceipt - fulfillmentProof - trackingDocumentation - accessConfirmation - serviceCompletion - productDescription - cancellationPolicy - refundProof - refundPolicy - disputeWithdrawal - supportingDocuments - otherEvidence type: string description: type: string required: - purpose - description additionalProperties: false recordedEvidence: type: array items: type: object properties: code: type: string description: type: string available: type: boolean required: - code - description - available additionalProperties: false required: - responseReasons - information - missingFields - recommendedDocuments - recordedEvidence additionalProperties: false title: ChargebackEvidenceGuidance timeline: type: array items: type: object properties: eventType: type: string description: Public chargeback event name. effectiveAt: type: string format: date-time description: When the event took effect. required: - eventType - effectiveAt additionalProperties: false description: Provider-visible case events, oldest first. version: type: integer exclusiveMinimum: 0 description: >- Version of the case and saved evidence. Use this version when saving, previewing, submitting, or accepting. createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - amount - currency - status - network - reason - responseDueAt - internalDueAt - paymentCreatedAt - submittedAt - allowedActions - counterUnavailableReason - evidence - evidenceGuidance - timeline - version - createdAt - updatedAt additionalProperties: false relationships: type: object properties: cardPayment: type: object properties: data: type: object properties: type: description: Resource type. Always `cardPayment`. type: string enum: - cardPayment id: type: string pattern: ^cpy_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship paymentIntent: type: object properties: data: type: object properties: type: description: Resource type. Always `paymentIntent`. type: string enum: - paymentIntent id: type: string pattern: ^pmi_[0-9a-f]{32}$ required: - type - id additionalProperties: false title: ResourceIdentifier description: Related resource identifier. required: - data additionalProperties: false title: ToOneRelationship 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 required: - cardPayment - paymentIntent - customerParty additionalProperties: false required: - id - type - attributes - relationships additionalProperties: false title: Chargeback 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: - id: cbk_019d0a1b2c3d4e5f60718293a4b5c700 type: chargeback attributes: amount: 4620 currency: USD status: needsResponse network: visa reason: category: notReceived networkCode: '13.1' description: Merchandise or services not received responseDueAt: '2026-09-27T23:59:59.999Z' internalDueAt: '2026-09-25T23:59:59.999Z' paymentCreatedAt: '2026-09-01T14:02:11.000Z' submittedAt: null allowedActions: - accept - counter counterUnavailableReason: null evidence: responseReason: receivedProduct product: type: physical shipTo: null carrier: UPS trackingNumber: 1Z9990000000000001 shippedOn: '2026-09-14' productDescription: A cotton shirt explanation: The cardholder confirmed receiving the order. deliveryDetails: null usageDetails: null cardholderName: null cardholderEmail: null cardholderPhone: null billingAddress: null billingPostalCode: null refundPolicyDisclosure: null refundDetails: null attachments: [] evidenceGuidance: responseReasons: - value: receivedProduct description: The cardholder received the product warning: null information: [] missingFields: [] recommendedDocuments: - purpose: fulfillmentProof description: Delivery confirmation for the disputed order recordedEvidence: - code: paymentRecord description: Recorded payment amount, date, and reference available: true timeline: - eventType: opened effectiveAt: '2026-09-17T12:00:00.000Z' version: 2 createdAt: '2026-09-17T12:00:00.000Z' updatedAt: '2026-09-17T12:02:00.000Z' relationships: cardPayment: data: type: cardPayment id: cpy_019d0a1b2c3d4e5f60718293a4b5c6d8 paymentIntent: data: type: paymentIntent id: pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 customerParty: data: type: party id: pty_019cd1798d627ad9bc302511c4f2c115 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 `. ````