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

# List events

> List events for the authenticated party, or for a delegated party if partyId is provided.



## OpenAPI

````yaml /api-reference/openapi.json get /events
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:
  /events:
    get:
      tags:
        - Events
      summary: List events
      description: >-
        List events for the authenticated party, or for a delegated party if
        partyId is provided.
      operationId: events.list
      parameters:
        - name: partyId
          in: query
          schema:
            type: string
            pattern: ^pty_[0-9a-f]{32}$
            description: Party ID to list events for (defaults to caller's party)
          allowEmptyValue: true
          allowReserved: true
        - name: eventType
          in: query
          schema:
            enum:
              - party.updated
              - compliance_case.updated
              - wallet.created
              - external_account.connected
              - agent_delegation_invitation.created
              - agent_delegation_invitation.accepted
              - agent_delegation_invitation.declined
              - agent_delegation_invitation.canceled
              - agent_delegation.revoked
              - delegation.activated
              - delegation.revoked
              - deposit.created
              - deposit.completed
              - deposit.failed
              - deposit.returned
              - deposit.canceled
              - deposit.approval_denied
              - withdrawal.created
              - withdrawal.completed
              - withdrawal.failed
              - withdrawal.returned
              - withdrawal.canceled
              - withdrawal.approval_denied
              - payment.created
              - payment.completed
              - payment.failed
              - payment.returned
              - payment.canceled
              - payment.approval_denied
              - approval.required
              - approval.approved
              - approval.denied
              - approval.canceled
              - payment_request.created
              - payment_request.completed
              - payment_request.canceled
              - payment_request.declined
              - payment_request.incoming
            type: string
            description: Filter by event type
          allowEmptyValue: true
          allowReserved: true
        - name: createdAfter
          in: query
          schema:
            type: string
            format: date-time
            description: Return events created after this timestamp (ISO 8601)
          allowEmptyValue: true
          allowReserved: true
        - name: createdBefore
          in: query
          schema:
            type: string
            format: date-time
            description: Return events created before this timestamp (ISO 8601)
          allowEmptyValue: true
          allowReserved: true
        - name: cursor
          in: query
          schema:
            type: string
            description: Cursor for keyset pagination
          allowEmptyValue: true
          allowReserved: true
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            description: Max items per page (1-100)
          allowEmptyValue: true
          allowReserved: true
        - 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.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          description: Resource type
                          type: string
                          enum:
                            - event
                        id:
                          type: string
                          description: Resource ID (evt_xxx)
                        attributes:
                          type: object
                          properties:
                            eventType:
                              enum:
                                - party.updated
                                - compliance_case.updated
                                - wallet.created
                                - external_account.connected
                                - agent_delegation_invitation.created
                                - agent_delegation_invitation.accepted
                                - agent_delegation_invitation.declined
                                - agent_delegation_invitation.canceled
                                - agent_delegation.revoked
                                - delegation.activated
                                - delegation.revoked
                                - deposit.created
                                - deposit.completed
                                - deposit.failed
                                - deposit.returned
                                - deposit.canceled
                                - deposit.approval_denied
                                - withdrawal.created
                                - withdrawal.completed
                                - withdrawal.failed
                                - withdrawal.returned
                                - withdrawal.canceled
                                - withdrawal.approval_denied
                                - payment.created
                                - payment.completed
                                - payment.failed
                                - payment.returned
                                - payment.canceled
                                - payment.approval_denied
                                - approval.required
                                - approval.approved
                                - approval.denied
                                - approval.canceled
                                - payment_request.created
                                - payment_request.completed
                                - payment_request.canceled
                                - payment_request.declined
                                - payment_request.incoming
                              type: string
                              description: Type of event
                            resourceId:
                              type: string
                              description: ID of the resource that triggered the event
                            resourceType:
                              type: string
                              description: Type of the resource (e.g. wallet, payment)
                            payload:
                              type: object
                              properties:
                                object:
                                  description: Point-in-time resource snapshot
                              additionalProperties: {}
                              description: >-
                                Event payload containing the resource snapshot.
                                Additional keys may be added in the future.
                            createdAt:
                              type: string
                              format: date-time
                              description: Creation timestamp (ISO 8601)
                          required:
                            - eventType
                            - resourceId
                            - resourceType
                            - payload
                            - createdAt
                          additionalProperties: false
                          title: EventAttributes
                          description: Resource 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 event
                          required:
                            - party
                          additionalProperties: false
                          title: EventRelationships
                          description: Resource relationships
                      required:
                        - type
                        - id
                        - attributes
                        - relationships
                      additionalProperties: false
                      title: EventResource
                  meta:
                    type: object
                    properties:
                      pagination:
                        type: object
                        properties:
                          hasMore:
                            type: boolean
                          nextCursor:
                            anyOf:
                              - type: string
                              - type: 'null'
                        required:
                          - hasMore
                          - nextCursor
                        additionalProperties: false
                        title: PaginationMeta
                    required:
                      - pagination
                    additionalProperties: false
                required:
                  - data
                  - meta
                additionalProperties: false
              examples:
                default:
                  summary: Default
                  value:
                    data:
                      - type: event
                        id: evt_0192abc1def2789034567890abcdef12
                        attributes:
                          eventType: wallet.created
                          resourceId: wal_7c9e6679e29b41d4a716446655440001
                          resourceType: wallet
                          payload:
                            object:
                              partyId: pty_7c9e6679e29b41d4a716446655440001
                              tier: standard
                              status: active
                              displayName: My Wallet
                              supportedAssets:
                                - usd
                              freezeDetails: null
                              createdAt: '2026-03-16T12:00:00Z'
                              updatedAt: '2026-03-16T12:00:00Z'
                              createdBy: usr_550e8400e29b41d4a716446655440000
                              version: 1
                          createdAt: '2026-03-16T12:00:00Z'
                        relationships:
                          party:
                            data:
                              type: party
                              id: pty_7c9e6679e29b41d4a716446655440001
                    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
                            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

````