Airbyte连接器构建器测试正常但创建源报401/403问题排查

背景场景 #

使用Airbyte Connector Builder为某HTTP API创建自定义连接器，curl手动调用API正常，Connector Builder内点击「测试」也能成功返回数据，但发布连接器并创建Source时，连接检查阶段出现401（未授权）或403（禁止访问）错误。

正常请求示例（curl） #

curl -X POST https://cliente.havan.com.br/ClubePontuacao/Api/Venda/Lotes \
  -H "Authorization: Bearer MY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Inicio": "2026-02-18T00:00:00",
    "Fim": "2026-02-24T23:59:59"
  }'

API要求：

• 请求方法为POST
• 携带Authorization: Bearer <token>请求头
• 请求体为包含Inicio和Fim字段的JSON

问题现象 #

Connector Builder流测试正常，但发布连接器后创建新Source时，出现以下两类错误：

错误1（403 Forbidden） #

Failed to save <source_name> due to the following error:
"Stream havan_api_raw_data is not available:
HTTP Status Code: 403. Error: Forbidden.
You don't have permission to access this resource."

错误2（401 Unauthorized） #

Unauthorized. Please ensure you are authenticated correctly.

'POST' request to 'https://cliente.havan.com.br/ClubePontuacao/Api/Venda/Lotes'
failed with status code '401' and error message: 'None'.

Response body:
{"Mensagem":"Token inválido ou não informado."}

当前连接器YAML配置 #

version: 7.0.4

type: DeclarativeSource

check:
  type: CheckStream
  stream_names:
    - havan_api_raw_data

streams:
  - type: DeclarativeStream
    name: havan_api_raw_data
    retriever:
      type: SimpleRetriever
      decoder:
        type: JsonDecoder
      requester:
        type: HttpRequester
        url: https://cliente.havan.com.br/ClubePontuacao/Api/Venda/Lotes
        http_method: POST
        authenticator:
          type: BearerAuthenticator
          api_token: "{{ config['api_key'] }}"
        request_headers:
          Content-Type: application/json
          Accept: application/json
          User-Agent: PostmanRuntime/7.37.3
        request_body:
          type: RequestBodyJsonObject
          value:
            Inicio: "{{ (now_utc() - duration('P20D')).strftime('%Y-%m-%dT00:00:00') }}"
            Fim: "{{ (now_utc() - duration('P14D')).strftime('%Y-%m-%dT23:59:59') }}"
      record_selector:
        type: RecordSelector
        extractor:
          type: DpathExtractor
          field_path:
            - Lotes
            - "*"
            - Itens
            - "*"

spec:
  type: Spec
  connection_specification:
    type: object
    $schema: http://json-schema.org/draft-07/schema#
    required:
      - api_key
    properties:
      api_key:
        type: string
        title: API Token
        airbyte_secret: true

Source创建时的配置 #

{
  "api_key": "MY_TOKEN"
}

疑惑点 #

• curl调用API完全正常
• Connector Builder内测试流能成功返回数据
• 发布后创建Source时同一端点报错
• 错误响应表明连接检查阶段未正确发送Token

额外日志信息 #

Airbyte日志中出现过：

Unable to find spec.yaml or spec.json in the package.
FileNotFoundError: Unable to find spec.yaml or spec.json in the package.

核心问题 #

1. 为何Connector Builder流测试正常，但创建Source时同一请求报401/403？
2. Connector Builder测试、已发布自定义连接器运行时、Source连接检查三者的已知差异是什么？
3. 此处使用BearerAuthenticator是否正确，还是应使用ApiKeyAuthenticator显式注入Authorization: Bearer ...头？

问题分析与解决方案 #

1. 核心原因：spec文件缺失导致配置无法正确读取 #

日志中出现的Unable to find spec.yaml or spec.json是关键问题。Connector Builder测试时直接加载本地YAML配置，而发布后的连接器需要通过spec文件来解析用户输入的配置参数（包括api_key）。如果包内缺失spec文件，Airbyte无法正确读取用户配置的Token，导致请求未携带有效认证头，触发401/403错误。

2. 三者的差异说明 #

• Connector Builder测试：在Builder环境中直接执行请求逻辑，使用测试时输入的配置参数，跳过了完整的连接器打包与配置解析流程，因此能正确注入Token。
• 已发布自定义连接器运行时：需要完整的包结构（包含spec.yaml/spec.json），Airbyte通过spec文件验证并读取用户配置，再传递给连接器执行请求。
• Source连接检查：创建Source时触发连接器的CheckStream逻辑，此时需要连接器能通过spec文件正确读取用户配置，生成带有效认证的请求。若配置读取失败，就会出现认证错误。

3. 修复步骤 #

（1）确保发布的连接器包包含spec.yaml

发布自定义连接器时，确认spec.yaml文件被正确打包到连接器包中。Airbyte依赖该文件解析用户配置，缺失会导致api_key无法传递到请求中。

（2）验证BearerAuthenticator的使用（或替换为显式配置）

BearerAuthenticator的设计就是自动生成Authorization: Bearer <token>头，当前配置本身是正确的。但如果存在兼容性问题，可以替换为ApiKeyAuthenticator显式构造认证头，配置如下：

authenticator:
  type: ApiKeyAuthenticator
  api_key: "{{ config['api_key'] }}"
  api_key_header: "Authorization"
  header_prefix: "Bearer"

（3）检查请求日志确认认证头

查看Airbyte的连接器运行日志，确认请求是否携带了正确的Authorization头，验证api_key是否被正确注入。

（4）验证请求体时间参数（次要）

虽然报错是认证问题，但可以确认Inicio和Fim的时间格式是否完全符合API要求，避免因请求体格式问题间接导致的权限报错。

内容的提问来源于stack exchange，提问作者Luan Ramos