SDK
常见集成问题 FAQ
汇总开发者在接入翠鸟 SDK 过程中最常遇到的问题与解决方案
认证与连接
初始化 SDK 后调用任何方法都返回 401 错误，怎么排查？
401 错误表示 API Key 无效或未正确传入。请按以下步骤排查：
- 确认使用的是控制台 — 开发者设置 中显示的完整 Key（包含
ck_live_或ck_test_前缀） - 检查 Key 是否已被撤销（控制台 — API Keys 列表中状态应为"活跃"）
- 确认环境变量名称拼写正确，运行
echo $CUINIAO_API_KEY验证是否正确加载 - 注意测试密钥（
ck_test_）只能用于开发环境，生产请求需使用生产密钥
在企业内网环境下 SDK 无法连接到 API，如何配置代理？
SDK 支持通过 Builder 模式配置 HTTP 代理：
// Java
CuiniaoClient client = new CuiniaoClient.Builder()
.apiKey("ck_live_xxx")
.proxy("http://proxy.internal.company.com", 8080)
.build();
# Python
client = CuiniaoClient(
api_key="ck_live_xxx",
proxy="http://proxy.internal.company.com:8080"
)
如果代理需要认证，额外传入 proxyUsername 和 proxyPassword 参数。
SDK 请求超时了，默认超时时间是多少？如何调整？
默认连接超时为 5秒，读取超时为 30秒。对于上传大文件，建议适当增大读取超时：
// Java - 调整超时
CuiniaoClient client = new CuiniaoClient.Builder()
.apiKey("ck_live_xxx")
.connectTimeoutSeconds(10)
.readTimeoutSeconds(120) // 上传大文件时建议设为120秒
.build();
数据与功能
为什么通过 API 上传的内容状态一直是 draft，访客无法访问？
通过 API 创建的内容默认为 draft 状态，需要显式发布才能对外访问。有两种方式发布：
- 调用发布接口：
POST /v1/resources/{id}/publish - 创建时在请求体中加入
"auto_publish": true参数（v3.1.0+ 支持）
// 创建时直接发布（Java）
client.resources().create(
CreateRequest.builder()
.title("营销白皮书")
.type("article")
.autoPublish(true)
.build()
);
如何拉取所有线索，API 有数量限制吗？
单次请求最多返回 100条线索。如需获取全部数据，请使用游标分页：
# Python - 游标分页获取全部线索
all_leads = []
cursor = None
while True:
resp = client.leads.list(limit=100, cursor=cursor)
all_leads.extend(resp["data"])
cursor = resp.get("next_cursor")
if not cursor:
break
print(f"共获取 {len(all_leads)} 条线索")
Webhook 签名验证总是失败，可能是什么原因？
签名验证失败的常见原因：
- 请求体被框架预处理：签名基于原始请求体计算，Express.js 需用
express.raw()而非express.json()接收请求 - Signing Secret 使用错误：应使用 Webhook 端点创建时返回的
signing_secret，而不是 API Key - 时间戳过期：翠鸟会拒绝时间戳与当前时间相差超过5分钟的请求，确保服务器时间同步（NTP）
详细验证逻辑请参阅 签名验证文档。
在 Spring Boot 项目中如何将 CuiniaoClient 注入为 Bean？
建议通过配置类创建单例 Bean，避免重复初始化连接池：
@Configuration
public class CuiniaoConfig {
@Value("0")
private String apiKey;
@Bean
@Singleton
public CuiniaoClient cuiniaoClient() {
return new CuiniaoClient.Builder()
.apiKey(apiKey)
.build();
}
}
在 application.properties 中配置：cuiniao.api-key=
SDK 在高并发场景下频繁出现连接池耗尽错误，如何优化？
默认连接池最大并发为 20。高并发场景建议：
- 调大连接池：
.maxConnections(50) - 使用异步 API（
*Async方法）配合线程池，避免同步阻塞 - 对批量操作使用 Batch 接口而非循环调用单条接口
- 合理设置请求超时，避免慢请求长时间占用连接
详细优化方案请参阅 性能优化指南。