> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 撤销银行连接 API：终止访问权限

> Didit 的撤销银行连接端点可终止对银行的访问，调用后，银行数据获取会立即停止。

Didit 的撤销银行连接端点会停止访问该银行，撤销请求发出后，银行数据拉取会立即停止。
撤销不会删除任何内容。如需删除，请使用[删除](https://docs.didit.me/zh/standalone-apis/bank-connection-delete.md)。
同意记录的状态先显示为 `revocation_pending`，银行确认后变为 `revoked`。


## OpenAPI

````yaml zh/openapi-25.json POST /v3/bank/connections/{id}/revoke/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags:
  - name: Bank Data
    description: >-
      银行数据服务涵盖银行链接、连接、账户、余额、交易、机构和覆盖范围。银行数据可用于沙盒应用。在宣布开放生产访问之前，生产应用的调用将返回
      `404`。沙盒环境不收费。使用 API
      密钥进行的调用，需要具备银行数据权限（`bank-data`）的密钥：读取操作需要读取权限，会更改数据的操作需要写入权限。账户核验是例外，它需要会话的写入权限或完全访问权限，而不需要银行数据权限。银行数据不属于完全访问权限的一部分：完全访问密钥会被拒绝，调用返回
      `403
      bank_data_access_denied`，直到您创建具备该权限的密钥为止。原始银行数据（账户、余额、交易以及变更流）同样会拒绝不携带 API
      密钥的请求。


      除账户核验外，`/v3/bank/` 下的每个拒绝响应都具有相同的 JSON
      结构（`code`、`message`、`request_id`、`field`、`next_action`、`retry_after`）。不是操作的路径、不是
      UUID 的 ID 或未知的子资源，对于所有方法都返回 `404 not_found`；任何意外错误都返回 `500 internal_error`
      及 `request_id`。在银行数据不可用时，每个操作都返回平台标准的 `404`，与访问未知路由时完全相同。
paths:
  /v3/bank/connections/{id}/revoke/:
    post:
      tags:
        - Bank Data
      summary: 撤销银行连接
      description: >-
        停止对银行的访问。你发起请求后，银行数据获取会立即停止，即使银行的确认仍在等待中：同意状态为
        `revocation_pending`；银行确认访问已终止后变为 `revoked`；若调用正在自动重试，则为
        `revocation_failed`。`consent.ended_by` 为 `customer`。


        撤销不会删除任何数据：已存储的账户、余额和交易在
        `consent.retain_until`（即你的应用的保留设置）之前仍可读取，且不收取任何费用。若要立即删除，请调用
        `delete_connection`。重复调用将返回当前状态。


        需要具有银行数据权限（`bank-data`）的 API
        密钥：此操作属于写入操作，会改变数据。拥有完全访问权限的密钥不包含该权限：创建密钥时需要显式授予，否则调用将返回 `403
        bank_data_access_denied`。


        撤销已删除的连接时，将返回 `200` 和已删除的连接，因此重复调用是安全的。
      operationId: revokeBankConnection
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: 连接 ID。
        - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: 包含撤销状态的连接。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankConnection'
              examples:
                Revocation pending:
                  summary: 已请求停止访问
                  value:
                    id: 5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35
                    environment: live
                    access: ongoing
                    status: active
                    status_reason: null
                    institution:
                      id: es-banco-norte
                      name: Banco Norte
                      country: ESP
                      logo_url: https://static.example.com/banks/es-banco-norte.png
                    segment: business
                    data:
                      - accounts
                      - balances
                      - transactions
                    consent:
                      status: revocation_pending
                      version: 1
                      granted_at: '2026-11-21T12:04:11Z'
                      expires_at: '2027-05-20T12:04:11Z'
                      days_granted: 180
                      renewed_count: 0
                      scopes_requested:
                        - accounts
                        - balances
                        - transactions
                      scopes_granted:
                        - accounts
                        - balances
                        - transactions
                      accounts_granted:
                        - a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        - c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                      renewal_action: bank_auth
                      renew_by: '2027-05-20T12:04:11Z'
                      reconfirm_by: null
                      renewable_until: '2026-12-21T15:10:00Z'
                      retain_until: '2026-12-21T15:10:00Z'
                      ended_at: '2026-11-21T15:10:00Z'
                      ended_by: customer
                    sync:
                      status: ok
                      initial_status: succeeded
                      initial_complete: true
                      history_complete: true
                      last_synced_at: '2026-11-21T12:04:40Z'
                      next_sync_at: '2026-11-22T06:00:00Z'
                      budgets:
                        - scope: connection
                          resource: all
                          limit: 4
                          remaining: 3
                          resets_at: '2026-11-22T00:00:00Z'
                      last_error: null
                      frequency_per_day: 1
                      live_syncs_left_today: 3
                    accounts:
                      - id: a71f0c2e-5d38-4b96-a1c4-3e9f8d2b7a10
                        name: Cuenta negocio
                        type: current
                        usage: business
                        currency: EUR
                        iban_last4: '1332'
                        status: open
                      - id: c3d84e19-2a7b-4f60-b5e1-9a0c6d3f8e72
                        name: Cuenta de ahorro
                        type: savings
                        usage: business
                        currency: EUR
                        iban_last4: '7708'
                        status: open
                    ownership:
                      compare: none
                      match: null
                      check_id: null
                      result: null
                    end_user:
                      reference: client-7731
                    manage_url: null
                    billing:
                      unit: connection_month
                      price_usd: '0.9000'
                      billed_through: '2026-11-30'
                    possible_duplicate_of: null
                    erasure: null
                    vendor_data: client-7731
                    created_at: '2026-11-21T12:03:02Z'
                    updated_at: '2026-11-21T12:04:40Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/BankDataAccessDenied'
        '404':
          description: 该资源在此应用和环境中不存在。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankDataError'
              examples:
                Not found:
                  summary: 未找到
                  value:
                    code: not_found
                    message: The resource does not exist.
                    request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                    field: null
                    next_action: null
                    retry_after: null
        '429':
          $ref: '#/components/responses/RateLimitedWrite'
        '500':
          $ref: '#/components/responses/BankDataInternalError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -X POST
            'https://verification.didit.me/v3/bank/connections/5e1d2a70-3b94-4c1f-8a6e-d2f07b9c1e35/revoke/'
            \
              -H 'x-api-key: YOUR_API_KEY'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.bank.revoke_connection(
                "11111111-2222-3333-4444-555555555555",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: >-
            import Didit from "@didit-protocol/sdk-node";


            // Reads DIDIT_API_KEY.

            const didit = new Didit();


            const result = await
            didit.bank.revokeConnection("11111111-2222-3333-4444-555555555555");

            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.RevokeConnection(ctx, \"11111111-2222-3333-4444-555555555555\", didit.BankRevokeConnectionParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.bank().revokeConnection("11111111-2222-3333-4444-555555555555");

            System.out.println(result);
        - lang: php
          label: PHP
          source: >-
            <?php


            require 'vendor/autoload.php';


            use Didit\DiditClient;


            // Reads DIDIT_API_KEY.

            $didit = new DiditClient();


            $result =
            $didit->bank->revokeConnection('11111111-2222-3333-4444-555555555555');

            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: >-
            require "didit"


            # Reads DIDIT_API_KEY.

            didit = Didit::Client.new


            result =
            didit.bank.revoke_connection("11111111-2222-3333-4444-555555555555")

            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await
            client.Bank.RevokeConnectionAsync("11111111-2222-3333-4444-555555555555");

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        您为单次操作选择的可选重试安全密钥，最长 255 个字符（可使用
        UUID）。使用相同密钥、endpoint、查询参数和请求体重复发送的请求，会返回第一次的响应，状态码和响应体均相同，且不会再次运行或计费。同一密钥若用于其他
        endpoint、查询参数或请求体，将返回 `409` `idempotency_key_reused`；若第一个请求仍在处理中，则返回
        `409` `idempotency_key_in_progress` 及 `Retry-After`。失败的请求（任何 `4xx` 或
        `5xx`）不会被存储，因此您可以使用相同密钥再次发送。无论您使用 API 密钥还是访问 token
        调用，密钥都归属于您的应用。请参阅[重试与幂等性](/zh/integration/api-errors#重试与幂等性)。
      schema:
        type: string
        minLength: 1
        maxLength: 255
  schemas:
    BankConnection:
      type: object
      description: >-
        该用户授权您的应用读取一家银行数据的许可。续期会保留连接 id 和所有账户 id。已删除的连接只返回
        `id`、`status`、`status_reason`、`created_at` 和
        `erasure`，其他字段均不存在，且其中不再保留任何银行、用户或账户数据。
      properties:
        id:
          type: string
          description: 连接的标识符。
          format: uuid
        environment:
          type: string
          enum:
            - live
            - sandbox
        access:
          type: string
          enum:
            - one_time
            - ongoing
        status:
          type: string
          enum:
            - pending
            - active
            - renewal_required
            - paused
            - revoked
            - deleted
            - failed
          description: >-
            `pending`：首次同步正在进行。`active`：同意有效。`renewal_required`：同意已结束，或银行要求用户重新登录；可读取到上次同步的数据，且不计费。`paused`：当月余额不足。`revoked`：用户、银行或您已停止访问。`deleted`：仅保留
            `id`、`status`、`status_reason`、`created_at` 和
            `erasure`。`failed`：首次同步从未成功。
        status_reason:
          type: string
          enum:
            - collection_complete
            - consent_expired
            - consent_lapsed
            - bank_requires_sign_in
            - revoked_by_end_user
            - revoked_by_bank
            - revoked_by_customer
            - insufficient_balance
            - paused_by_customer
            - first_sync_failed
            - deleted_by_customer
            - retention_elapsed
            - application_deleted
            - null
          description: >-
            连接处于该状态的原因。`paused_by_customer` 为保留值。若连接为
            `deleted`：`deleted_by_customer`、`consent_lapsed`、`retention_elapsed`
            或 `application_deleted`。
          nullable: true
        institution:
          $ref: '#/components/schemas/BankInstitutionSummary'
        segment:
          type: string
          enum:
            - personal
            - business
            - null
          nullable: true
        data:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
          description: 用户接受的权限范围。
        consent:
          $ref: '#/components/schemas/BankConnectionConsent'
        sync:
          $ref: '#/components/schemas/BankConnectionSync'
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankConnectionAccountSummary'
          description: 连接中每个账户的摘要。使用 `get_account` 读取完整账户信息。
        ownership:
          $ref: '#/components/schemas/BankConnectionOwnership'
        end_user:
          type: object
          properties:
            reference:
              type: string
              description: 您为该用户或企业分配的 ID。
              nullable: true
          required:
            - reference
        manage_url:
          type: string
          description: 该用户自己的访问页面。在访问页面可用之前为 `null`。
          nullable: true
          format: uri
        billing:
          $ref: '#/components/schemas/BankConnectionBilling'
        possible_duplicate_of:
          type: string
          description: 当此连接可能与另一个有效连接重复，但没有任何 `end_user.reference` 能确认匹配时设置。
          format: uuid
          nullable: true
        erasure:
          allOf:
            - $ref: '#/components/schemas/BankConnectionErasure'
          nullable: true
          description: 在 `delete_connection` 之后设置；否则为 `null`。
        vendor_data:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - status
        - status_reason
        - created_at
        - erasure
    BankDataError:
      type: object
      description: 所有银行数据操作的错误响应体。每个字段始终存在。
      properties:
        code:
          type: string
          enum:
            - ongoing_access_not_available
            - segment_not_available
            - window_not_available
            - history_window_ambiguous
            - redirect_url_not_registered
            - link_origin_not_allowed
            - bank_data_access_denied
            - connection_not_active
            - consent_expired
            - renewal_not_needed
            - renewal_window_expired
            - access_removed
            - refresh_limit_reached
            - cursor_expired
            - page_expired
            - invalid_cursor
            - page_token_mismatch
            - contract_rate_missing
            - insufficient_credits
            - invalid_request
            - not_found
            - internal_error
          description: 机器可读的错误代码。请据此分支处理，切勿依据 `message`。
        message:
          type: string
          description: 面向开发者的通俗说明。措辞可能变化，请勿解析。
        request_id:
          type: string
          description: 本次请求的标识符。联系支持团队时请提供此标识符。
        field:
          type: string
          description: 需要更正的请求字段（如果错误与某个字段有关）。否则为 `null`。
          nullable: true
        next_action:
          type: string
          enum:
            - retry_later
            - renew_connection
            - create_link
            - restart_from_cursor
            - restart_read
            - top_up_balance
            - enable_bank_data_access
            - contact_support
            - null
          description: 下一步应执行的操作，便于客户端无需猜测即可执行。没有标准的下一步时为 `null`。
          nullable: true
        retry_after:
          type: integer
          description: 重试前需等待的秒数。仅在触发速率限制和出现临时错误时设置，否则为 `null`。
          nullable: true
      required:
        - code
        - message
        - request_id
        - field
        - next_action
        - retry_after
      example:
        code: ongoing_access_not_available
        message: >-
          This bank cannot keep access open. Use access one_time or choose
          another bank.
        request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
        field: institution_id
        next_action: create_link
        retry_after: null
    BankInstitutionSummary:
      type: object
      description: 连接或链接所对应的银行。
      properties:
        id:
          type: string
          description: Didit 的银行标识符，为稳定的 slug。请将其用作 `institution_id`。
          example: es-banco-norte
        name:
          type: string
          description: 银行名称。
          example: Banco Norte
        country:
          type: string
          description: 银行所在国家/地区，ISO 3166-1 alpha-3。
          pattern: ^[A-Z]{3}$
          example: ESP
        logo_url:
          type: string
          description: 银行的徽标，无则为 `null`。
          nullable: true
          format: uri
      required:
        - id
        - name
        - country
        - logo_url
    BankConnectionConsent:
      type: object
      description: 该用户对此连接的同意。
      properties:
        status:
          type: string
          enum:
            - granted
            - expired
            - revocation_pending
            - revoked
            - revocation_failed
          description: >-
            在银行确认同意已终止之前，状态为 `revocation_pending`，之后变为
            `revoked`。`revocation_failed` 会自动重试。请求撤销后，银行数据拉取会立即停止。
        version:
          type: integer
          description: 同意的版本。续期会在同一连接上创建下一个版本。
        granted_at:
          type: string
          format: date-time
          nullable: true
        expires_at:
          type: string
          description: 银行的同意结束的时间，由银行设定，最长为 `consent_days`。
          format: date-time
          nullable: true
        days_granted:
          type: integer
          description: 同意授权的时长（天），与银行授予的一致。
          nullable: true
        renewed_count:
          type: integer
          description: 同意已续期的次数。
        scopes_requested:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        scopes_granted:
          type: array
          items:
            type: string
            enum:
              - accounts
              - balances
              - transactions
        accounts_granted:
          type: array
          items:
            type: string
            format: uuid
          description: 用户共享的账户 ID。
        renewal_action:
          type: string
          enum:
            - reconfirm
            - bank_auth
            - null
          description: >-
            续期方式：`reconfirm` 表示在银行和所在国家/地区规则允许的情况下，由用户在 Didit
            界面上确认，无需登录银行；`bank_auth` 表示登录银行。
          nullable: true
        renew_by:
          type: string
          description: 同意的结束时间：请在到期前续期，以避免中断。
          format: date-time
          nullable: true
        reconfirm_by:
          type: string
          description: 当 `renewal_action` 为 `reconfirm` 时设置：可再次确认的最后时限。
          format: date-time
          nullable: true
        renewable_until:
          type: string
          description: 同意结束后，同一连接可以被恢复的最后时间。此后用户需要重新连接。该时间与 `retain_until` 相同。
          format: date-time
          nullable: true
        retain_until:
          type: string
          description: 访问结束后设置：已存储数据可读取的时长，由您应用的保留设置决定。
          format: date-time
          nullable: true
        ended_at:
          type: string
          format: date-time
          nullable: true
        ended_by:
          type: string
          enum:
            - end_user
            - bank
            - customer
            - unknown
            - null
          description: 由证据确定的终止访问方。当银行和同步均未说明时为 `unknown`。
          nullable: true
      required:
        - status
        - version
        - granted_at
        - expires_at
        - days_granted
        - renewed_count
        - scopes_requested
        - scopes_granted
        - accounts_granted
        - renewal_action
        - renew_by
        - reconfirm_by
        - renewable_until
        - retain_until
        - ended_at
        - ended_by
    BankConnectionSync:
      type: object
      description: 连接的同步状态。
      properties:
        status:
          type: string
          enum:
            - pending
            - ok
            - failing
          description: >-
            连续 24 小时的失败尝试后为 `failing`，失败尝试会以退避方式重试。若银行要求用户重新登录，连接会改为
            `renewal_required`。
        initial_status:
          type: string
          enum:
            - pending
            - succeeded
            - partial
            - failed
          description: >-
            首次同步的结果。当结果为 `succeeded` 或 `partial` 时，连接变为
            `active`；当没有任何账户同步成功时，连接变为 `failed`。
        initial_complete:
          type: boolean
          description: 仅当 `initial_status` 为 `succeeded` 时返回 `true`：可读取账户、余额和近期交易。
        history_complete:
          type: boolean
          description: >-
            无论出于何种原因，历史数据回填结束时均返回 `true`。无法获取的范围位于每个账户的
            `history_coverage.missing_ranges` 中。
        last_synced_at:
          type: string
          description: 数据最后一次从银行获取的时间，而非您最后一次读取数据的时间。
          format: date-time
          nullable: true
        next_sync_at:
          type: string
          description: 下一次自动同步的计划时间。自动同步每天运行一到四次，具体取决于银行（参见 `frequency_per_day`）。
          format: date-time
          nullable: true
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/BankSyncBudget'
          description: 银行对用户不在场时获取操作的限制。
        last_error:
          allOf:
            - $ref: '#/components/schemas/BankSyncError'
          nullable: true
          description: 最近一次同步错误，无则为 `null`。
        frequency_per_day:
          type: integer
          minimum: 1
          maximum: 4
          description: 该连接的自动同步每天运行的次数，根据银行不同为一到四次。若银行允许更多无人值守读取，则始终至少保留每天两次用于实时同步。
        live_syncs_left_today:
          type: integer
          minimum: 0
          description: >-
            在银行限额内，当天剩余的实时同步次数（`refresh_connection`），即最严格配额的
            `remaining`。银行未设限额时为 `null`。实时同步包含在月度价格中。
          nullable: true
      required:
        - status
        - initial_status
        - initial_complete
        - history_complete
        - last_synced_at
        - next_sync_at
        - budgets
        - last_error
        - frequency_per_day
        - live_syncs_left_today
    BankConnectionAccountSummary:
      type: object
      description: 连接中账户的简写形式。
      properties:
        id:
          type: string
          description: 账户 ID。在连接的整个生命周期内保持稳定，续期后也不变。
          format: uuid
        name:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - current
            - savings
            - card
            - loan
            - investment
            - other
        usage:
          type: string
          enum:
            - personal
            - business
            - unknown
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 货币代码。
        iban_last4:
          type: string
          description: IBAN 的后四位字符（如果账户有 IBAN）。
          nullable: true
        status:
          type: string
          enum:
            - open
            - closed
            - access_removed
      required:
        - id
        - name
        - type
        - usage
        - currency
        - iban_last4
        - status
    BankConnectionOwnership:
      type: object
      description: 可选的账户持有人与个人或企业的比对结果。
      properties:
        compare:
          type: string
          enum:
            - none
            - person
            - business
        match:
          type: string
          enum:
            - any_holder
            - all_holders
            - null
          nullable: true
        check_id:
          type: string
          description: 请求比对时，所有权比对结果的 ID。
          format: uuid
          nullable: true
        result:
          type: string
          enum:
            - match
            - close_match
            - no_match
            - unknown
            - null
          description: 判定结果。只要缺失的持有人证据可能改变结果，或银行未共享持有人信息时，结果为 `unknown`。
          nullable: true
      required:
        - compare
        - match
        - check_id
        - result
    BankConnectionBilling:
      type: object
      description: 此连接的费用。沙盒环境从不计费。
      properties:
        unit:
          type: string
          description: 计费单位。持续访问为 `connection_month`，否则为 `one_time`。
          enum:
            - connection_month
            - one_time
        price_usd:
          type: string
          description: >-
            您今天针对应用和该国家/地区的月度计量价格，以美元计，为保留 4
            位小数的十进制字符串。只有当每个已接受的权限范围在该月内至少为一个账户发布了数据时，连接才会在该月计费。一次性连接和沙盒环境中为
            `null`。持续访问按每个活动连接每月计费；当前价格见定价页面（https://docs.didit.me/getting-started/pricing）。示例中的金额仅作说明；各国家/地区的价格见定价页面。
          pattern: ^-?\d+(\.\d+)?$
          nullable: true
        billed_through:
          type: string
          description: 已结算的最近一个月末日期。
          format: date
          nullable: true
      required:
        - unit
        - price_usd
        - billed_through
    BankConnectionErasure:
      type: object
      description: 您申请的删除操作的进度。
      properties:
        status:
          type: string
          enum:
            - pending
            - erased
            - failed
          description: >-
            `pending` 表示删除正在进行；`erased` 表示不再保留任何存储副本，且银行处也不再有访问权限；`failed` 表示未能在
            24 小时内确认。删除失败时，该连接的数据仍处于关闭状态，会被重试，并通知 Didit。
        requested_at:
          type: string
          format: date-time
        erased_at:
          type: string
          format: date-time
          nullable: true
          description: 删除完成的时间。`status` 为 `erased` 之前为 `null`。
      required:
        - status
        - requested_at
        - erased_at
    RateLimitBudgetError:
      type: object
      description: 仅在速率限制中间件预算拒绝时返回。其他 429 错误（包括幂等性冲突和端点特定上限）不保证返回这些元数据字段。
      required:
        - detail
        - reference
        - limit
        - remaining
        - reset
        - window_seconds
      properties:
        detail:
          type: string
          description: 已有的可读预算拒绝信息。
        reference:
          type: string
          pattern: ^RL-[0-9a-f]{32}$
          description: 不透明的支持参考编号：RL- 后跟 32 个小写 UUID 十六进制字符。
        limit:
          type: integer
          description: 超出限额的作用域对应的预算；与 X-RateLimit-Limit 相同。
        remaining:
          type: integer
          minimum: 0
          description: 剩余额度，下限为零；与 X-RateLimit-Remaining 相同。
        reset:
          type: integer
          format: int64
          description: 窗口重置时间，以 Unix 秒表示；与 X-RateLimit-Reset 相同。
        window_seconds:
          type: integer
          description: 固定窗口时长（秒），不是剩余等待时间。重试前请遵循 Retry-After。
      example:
        detail: >-
          Write request rate limit exceeded. You can make up to 300 requests per
          minute.
        reference: RL-00000000000040008000000000000001
        limit: 300
        remaining: 0
        reset: 1794358860
        window_seconds: 60
    BankSyncBudget:
      type: object
      description: 银行对用户不在场时获取数据所设限制中的一个额度分段。
      properties:
        scope:
          type: string
          enum:
            - connection
            - account
          description: 银行以什么为依据计算预算消耗。
        resource:
          type: string
          enum:
            - all
            - accounts
            - balances
            - transactions
        account_id:
          type: string
          description: 当 `scope` 为 `account` 时的账户。
          format: uuid
          nullable: true
        limit:
          type: integer
          description: 按银行定义，Didit 在用户不在场的情况下每天最多可从银行获取数据的次数。这是银行设定的上限，而非承诺值。
        remaining:
          type: integer
          description: 当前时间窗口内剩余的手动刷新次数。自动同步保留的读取次数已预先扣除，且自动同步从不占用当天最后两次读取，因此始终保留两次按需刷新的机会。
        resets_at:
          type: string
          description: 时间窗口重置的时间。
          format: date-time
      required:
        - scope
        - resource
        - limit
        - remaining
        - resets_at
    BankSyncError:
      type: object
      description: 同步失败的原因。
      properties:
        code:
          type: string
          description: Didit 错误代码。
        message:
          type: string
          description: 通俗说明。
        at:
          type: string
          description: 事件发生的时间。在单个账户的结果中为 `null`。
          format: date-time
          nullable: true
      required:
        - code
        - message
        - at
  responses:
    Unauthorized:
      description: 未授权
      content:
        application/json:
          examples:
            Invalid API Key:
              summary: API 密钥无效
              value:
                detail: Invalid API Key.
    BankDataAccessDenied:
      description: >-
        API 密钥不具有银行数据权限（`bank-data`），或者，对于生产环境应用中的原始银行数据，应用设置“Bank data in the
        API”已关闭。银行数据不属于完全访问权限：完全访问权限的密钥、仅限其他资源的密钥，以及未使用 API
        密钥认证的请求（客户端凭证，访问原始数据时）均会被以此响应体拒绝，因此请创建密钥并显式授予该权限。此拒绝发生在任何查询之前，因此不能说明对象是否存在。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Bank data not allowed:
              summary: 不允许访问银行数据
              value:
                code: bank_data_access_denied
                message: >-
                  Bank data calls need an API key that carries the Bank data
                  permission.
                request_id: 3f6a1c8e-92b5-4d07-a1e3-8c4b7f0d2e59
                field: null
                next_action: enable_bank_data_access
                retry_after: null
    RateLimitedWrite:
      description: 已超出每个 API 密钥每分钟 300 次请求的共享写入限制。重试前请遵循 `Retry-After`。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitBudgetError'
          example:
            detail: >-
              Write request rate limit exceeded. You can make up to 300 requests
              per minute.
            reference: RL-00000000000040008000000000000001
            limit: 300
            remaining: 0
            reset: 1794358860
            window_seconds: 60
      headers:
        Retry-After:
          $ref: '#/components/headers/BudgetRetryAfter'
        X-RateLimit-Scope:
          $ref: '#/components/headers/BudgetXRateLimitScope'
        X-RateLimit-Limit:
          $ref: '#/components/headers/BudgetXRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/BudgetXRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/BudgetXRateLimitReset'
    BankDataInternalError:
      description: >-
        Didit 端出现了问题。`/v3/bank/` 下的任何意外错误都以银行错误格式返回，绝不返回 HTML 页面：请将 `request_id`
        提供给支持团队。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BankDataError'
          examples:
            Internal error:
              summary: 意外错误
              value:
                code: internal_error
                message: >-
                  Something went wrong on our side. Quote the request_id to
                  support.
                request_id: 3f6a1c8e92b54d07a1e38c4b7f0d2e59
                field: null
                next_action: contact_support
                retry_after: null
  headers:
    BudgetRetryAfter:
      description: 需等待的秒数，向上取整到下一个时间窗口。出现在中间件预算拒绝响应中。
      schema:
        type: integer
    BudgetXRateLimitScope:
      description: 已超出预算的范围。出现在中间件预算拒绝响应中。
      schema:
        type: string
    BudgetXRateLimitLimit:
      description: 超出限额的作用域的预算；与请求体限制相同。出现在中间件预算拒绝响应中。
      schema:
        type: integer
    BudgetXRateLimitRemaining:
      description: 剩余额度，下限为零；与响应体中的 remaining 相同。仅出现在中间件额度拒绝的响应中。
      schema:
        type: integer
    BudgetXRateLimitReset:
      description: 以 Unix 秒表示的重置时间；与正文中的 reset 相同。出现在中间件预算拒绝响应中。
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        您的应用 API 密钥，可在 Business Console 的开发者 -> API
        密钥中获取。主密钥拥有完全访问权限。命名密钥可以设置范围：可按资源设置无权限、只读或读写，可限定为部分工作流或已批准的会话，可限定为一组 IP
        地址，并可设置过期日期。401 表示密钥错误、已被撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或执行该操作，或请求来自其 IP
        列表之外的地址；会话相关路由返回 404，表示该会话不在密钥的工作流或状态范围内。没有媒体访问权限的密钥会将图片、视频和 PDF 的 URL
        返回为 null；没有会话写入权限的密钥会将会话链接和令牌返回为 null。请参阅
        https://docs.didit.me/console/api-keys。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.