> ## 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.

# Create or refresh external account

> Link an external account on behalf of your customer using a Plaid processor token. If the account is already linked, refresh the existing connection and return the same external account with a 201 response.



## OpenAPI

````yaml /api-reference/openapi.json post /external-accounts/processor-token
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.co`


    Agents and coding assistants should prefer the hosted MCP server at
    `https://mcp.natural.co` 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.co
servers:
  - url: https://api.natural.co
    description: Production
security: []
tags:
  - name: Agents
    description: Agent management
  - name: Customers
    description: Customer management
  - name: Counterparties
    description: Counterparty management
  - name: Payments
    description: Payment operations
  - name: Transactions
    description: Transaction activity and history operations
  - name: Transfers
    description: Deposit and withdrawal operations
  - name: PaymentRequests
    description: Payment-request management
  - name: Approvals
    description: Approval review operations
  - name: Invitations
    description: Party invitation management
  - name: Identity
    description: Caller identity introspection
  - name: Parties
    description: Party and organization management
  - name: Wallets
    description: Wallet balance, deposits, withdrawals, and external accounts
  - name: External Accounts
    description: Linked external bank 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 access
paths:
  /external-accounts/processor-token:
    post:
      tags:
        - External Accounts
      summary: Create or refresh external account
      description: >-
        Link an external account on behalf of your customer using a Plaid
        processor token. If the account is already linked, refresh the existing
        connection and return the same external account with a 201 response.
      operationId: externalAccounts.createFromProcessorToken
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
          description: >-
            Unique key for idempotent request handling. If a request with the
            same key was already processed, the original response is returned.
        - name: X-Agent-ID
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
          description: Agent ID (agt_xxx) identifying which agent is making the request.
        - name: X-Instance-ID
          in: header
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 1024
              - type: 'null'
          description: >-
            Required when X-Agent-ID is present. Session or conversation ID for
            agent observability.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      type: object
                      properties:
                        partyId:
                          type: string
                          pattern: ^pty_[0-9a-f]{32}$
                          description: >-
                            Caller-owned end-customer party that will own the
                            linked external account. Must be the caller's own
                            party or a party with an approved delegated
                            relationship carrying external_accounts.create.
                        processorToken:
                          type: string
                          minLength: 1
                          description: >-
                            Plaid processor token minted by the customer's own
                            Plaid integration with /processor/token/create for
                            processor "natural". Scoped to exactly one account.
                        institutionName:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: >-
                            Optional institution display name to store with the
                            linked external account.
                      required:
                        - partyId
                        - processorToken
                      additionalProperties: false
                  required:
                    - attributes
                  additionalProperties: false
              required:
                - data
              additionalProperties: false
            examples:
              default:
                summary: Default
                value:
                  data:
                    attributes:
                      partyId: pty_7c9e6679e29b41d4a716446655440001
                      processorToken: processor-sandbox-abc123
                      institutionName: Chase
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          description: Resource type.
                          type: string
                          enum:
                            - externalAccount
                        id:
                          type: string
                          pattern: ^eac_[0-9a-f]{32}$
                          description: External account ID.
                        attributes:
                          type: object
                          properties:
                            lastFour:
                              type: string
                              description: Last four digits of the external bank account.
                            status:
                              enum:
                                - pending
                                - new
                                - active
                                - disabled
                                - deleted
                                - unknown
                              type: string
                              description: Lifecycle status of the external account.
                            connectionStatus:
                              enum:
                                - active
                                - login_required
                                - disconnected
                              type: string
                              description: >-
                                Provider connection health for this external
                                account. Poll this value to detect when the
                                underlying provider connection requires
                                attention.
                            createdAt:
                              type: string
                              format: date-time
                              description: Time when the external account was linked.
                            bankName:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Bank institution name, when available.
                            accountName:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Bank account display name, when available.
                            accountType:
                              anyOf:
                                - enum:
                                    - checking
                                    - savings
                                    - unknown
                                  type: string
                                - type: 'null'
                              description: Bank account type, when available.
                          required:
                            - lastFour
                            - status
                            - connectionStatus
                            - createdAt
                            - bankName
                            - accountName
                            - accountType
                          additionalProperties: false
                          title: ExternalAccountAttributes
                          description: External account attributes.
                        relationships:
                          type: object
                          properties:
                            party:
                              type: object
                              properties:
                                data:
                                  type: object
                                  properties:
                                    type:
                                      description: Resource type
                                      type: string
                                      enum:
                                        - party
                                    id:
                                      type: string
                                  required:
                                    - type
                                    - id
                                  additionalProperties: false
                                  title: ResourceIdentifier
                                  description: Related resource identifier
                              required:
                                - data
                              additionalProperties: false
                              title: ToOneRelationship
                              description: Party that owns the external account.
                          required:
                            - party
                          additionalProperties: false
                          title: ExternalAccountRelationships
                          description: External account relationships.
                      required:
                        - type
                        - id
                        - attributes
                        - relationships
                      additionalProperties: false
                      title: ExternalAccountResource
                    description: External accounts linked or refreshed by the request.
                  meta:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          hasMore:
                            type: boolean
                          nextCursor:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - hasMore
                          - nextCursor
                        additionalProperties: false
                        title: PaginationMeta
                      rejectedAccounts:
                        type: array
                        items:
                          type: object
                          properties:
                            accountId:
                              type: string
                              description: >-
                                Aggregator account identifier for the rejected
                                account.
                            accountName:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Display name of the rejected account.
                            accountMask:
                              anyOf:
                                - type: string
                                - type: 'null'
                              description: Last-four mask of the rejected account.
                            reason:
                              enum:
                                - profile_identity_missing
                                - bank_identity_unavailable
                                - bank_account_name_mismatch
                                - bank_account_address_mismatch
                                - bank_account_ownership_mismatch
                                - bank_account_verification_failed
                              type: string
                              description: >-
                                Product-safe reason code explaining why the
                                account was not linked.
                          required:
                            - accountId
                            - accountName
                            - accountMask
                            - reason
                          additionalProperties: false
                          title: ExternalAccountRejectedAccount
                        description: Accounts Natural inspected but did not link.
                    required:
                      - pagination
                      - rejectedAccounts
                    additionalProperties: false
                required:
                  - data
                  - meta
                additionalProperties: false
                title: ExternalAccountListWithRejectedAccountsResponse
              examples:
                default:
                  summary: Default
                  value:
                    data:
                      - type: externalAccount
                        id: eac_550e8400e29b41d4a716446655440000
                        attributes:
                          bankName: Chase
                          accountName: Plaid Checking
                          accountType: checking
                          lastFour: '0000'
                          status: active
                          connectionStatus: active
                          createdAt: '2026-01-04T15:30:00Z'
                        relationships:
                          party:
                            data:
                              type: party
                              id: pty_7c9e6679e29b41d4a716446655440001
                    meta:
                      pagination:
                        hasMore: false
                        nextCursor: null
                      rejectedAccounts: []
          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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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: A request value is invalid.
                        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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
          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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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: 'email: Invalid email address'
                        status: '422'
                        source:
                          pointer: /data/attributes/email
                        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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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
                            parameter:
                              type: string
                            header:
                              type: string
                          additionalProperties: false
                        meta:
                          type: object
                          description: >-
                            Error metadata. Public responses include supportId
                            by default and may include allowlisted provider
                            recovery metadata.
                          properties:
                            supportId:
                              type: string
                              description: Request/support ID for troubleshooting
                            connectionStatus:
                              type: string
                              enum:
                                - login_required
                                - disconnected
                              description: >-
                                External account connection state when the error
                                is repairable by relinking
                            provider:
                              type: object
                              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

````