Webhook 地址请求超时错误码 60011 怎么排查？

很多开发者在对接 Webhook 时，看到请求失败且伴随错误码 60011，容易误判为网络超时。实际上，在主流平台（如企业微信）中，60011 通常代表权限或认证问题，而非网络层超时。真正的网络超时通常表现为 HTTP 状态码 504 或 408。

先说结论：错误码 60011 在大多数 API 平台（尤其是企业微信）中表示“权限不足”或“认证参数无效”，与网络超时无关。排查时应优先检查接口权限开通情况及 appkey、secret 等认证参数。

确认平台：查看对应平台文档确认 60011 定义
检查权限：登录管理后台确认接口权限已开通
核对参数：确保 appkey 或 token 传递位置正确

核心区别：业务错误 vs 网络超时

排查前需明确区分“业务层错误”与“网络层超时”，两者的响应特征完全不同：

1. 业务错误（如 60011）：请求已到达服务器，服务器处理后发现权限不足，返回 HTTP 200 但 body 中包含错误码。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "errcode": 60011,
    "errmsg": "no permission to access api"
}

2. 网络超时（如 504/408）：请求未完整到达服务器或网关等待过久，通常没有业务 JSON 响应。

HTTP/1.1 504 Gateway Timeout
Content-Type: text/html

<html><body><h1>504 Gateway Time-out</h1></body></html>

分步排查与实操

步骤 1：确认平台错误码定义

不同平台对 60011 的定义可能不同。以企业微信为例，60011 明确代表“No Permission”。如果是自建系统，需查阅内部文档确认是否自定义了该码为超时。

步骤 2：检查认证参数传递

确保认证参数（appkey、token 等）传递位置符合文档要求。常见错误是将其放在 Body 中而接口要求放在 Header 或 URL 中。

Python 请求示例（正确传递参数）：

import requests

url = "https://api.example.com/v1/webhook?timestamp=1715660000&appkey=YOUR_APPKEY"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN"
}
data = {"msg": "test"}

response = requests.post(url, json=data, headers=headers)
print(response.status_code, response.json())

步骤 3：使用 curl 验证连通性与响应

使用 curl 命令可以快速区分是网络不通还是业务拒绝。添加 -v 参数查看完整交互：

curl -v -X POST "https://api.example.com/v1/webhook?appkey=YOUR_APPKEY" \
  -H "Content-Type: application/json" \
  -d '{"msg":"test"}'

观察输出：如果看到 HTTP/1.1 200 OK 但 body 中有 60011，说明网络通畅，是权限问题；如果看到 Connection timed out 或 504，则是网络问题。

验证修复是否生效

1. 观察错误码变化：修复权限或参数后，再次请求，errcode 应消失或变为 0（成功）。

2. 检查服务端日志：登录 API 提供方后台，查看接口调用日志，确认状态从“鉴权失败”变为“调用成功”。

3. Webhook 投递状态：在管理后台查看事件投递记录，确认不再显示“验证失败”或“权限错误”。

常见坑与注意事项

1. 不要依赖 errmsg 判断：错误消息文本可能会调整，始终以 errcode 数字为准。

2. 参数位置敏感：部分接口要求 appkey 放在 URL 查询参数，部分要求放在 Header，混用会导致 60011。

3. 权限开通滞后：在管理后台开通权限后，可能需要等待几分钟生效，立即请求仍可能报错。

4. HTTPS 证书问题：如果客户端禁止不安全证书，可能导致连接失败，但这通常抛出异常而非返回 60011。