API Reference
错误
CN /v1 API 通用错误结构、状态码、重试策略和排查字段。
错误
CN /v1 API 错误响应使用嵌套 JSON 结构。客户端应优先读取 error.code、error.message 和 error.requestId。
{
"error": {
"code": "invalid_request",
"message": "Invalid request",
"requestId": "req_xxx"
}
}部分错误会携带额外字段，例如 supportedModels。客户端应允许 error 对象存在额外属性，不要用严格 schema 丢弃它们。
通用状态码
| 状态码 | 含义 | 是否建议自动重试 |
|---|---|---|
400 | 请求体、路径参数、查询参数或 URL 字段错误 | 否。应修正请求 |
401 | API Token 缺失、无效或已撤销 | 否。应检查密钥和环境 |
402 | 额度或积分不足 | 否。应充值或降低任务规模 |
403 | 当前账户无权访问该资源、模型或能力 | 否。应检查权限 |
404 | 查询的任务不存在或不属于当前账户 | 通常否。应确认 taskId |
500 | 服务端错误、数据库错误或供应商错误 | 是。有限次数退避重试 |
不同接口返回的状态码集合略有不同。同步 TTS 常见 400、401、403、402、500；任务详情接口还可能返回 404。
常见错误码
| code | 常见触发原因 |
|---|---|
unauthorized | 没有 Authorization: Bearer、token 错误、token 已撤销 |
forbidden | Token 有效但无权访问该能力、模型或任务 |
invalid_request | JSON 无效、字段类型不正确、模型不支持、缺少条件字段 |
insufficient_credits | 余额不足以创建任务或同步生成 |
not_found | 任务不存在或不属于当前账户 |
generation_failed | 供应商生成失败或内部任务处理失败 |
具体 code 名称可能随服务端实现扩展。SDK 不应只依赖固定枚举；未知 code 也应保留原始字段并按 HTTP 状态码处理。
额度不足示例
扣费类接口可能返回：
{
"error": {
"code": "insufficient_credits",
"message": "Insufficient credits",
"requestId": "req_xxx"
}
}遇到 402 时，不要立即重试同一个请求。应查询 GET /v1/usage，确认余额、近期任务和 apiUsage.totalCreditsCharged，或者缩短文本、音频、视频任务规模。
同步 TTS 的解析规则
同步 TTS 成功时返回音频二进制：
HTTP/1.1 200 OK
Content-Type: audio/mpeg
x-kitta-request-id: req_xxx
x-kitta-credits-charged: 24只有错误响应才是 JSON。客户端应先判断状态码：
2xx：按Content-Type处理音频，并读取x-kitta-request-id、x-kitta-credits-charged。- 非
2xx：按错误 JSON 读取error对象。
任务接口重试策略
对任务创建接口，500 可以有限次数退避重试，但要避免重复创建任务：
- 你方系统应记录内部任务 ID、请求时间、模型、输入 URL 或文本摘要。
- 如果创建请求超时但不确定服务端是否成功，可以先查询任务列表，再决定是否重试。
- 对
400、401、402、403不应自动重试。
对任务详情和列表接口，建议每 3 到 5 秒查询一次。任务进入 succeeded 或 failed 后停止轮询。
排查字段
排查问题时请记录：
- HTTP 方法和路径，例如
POST /v1/tts/speech。 error.requestId或同步 TTS 成功响应头x-kitta-request-id。- 发生时间和时区。
- 你方内部用户 ID、任务 ID 或订单 ID。
- 响应状态码、
error.code、error.message。 - 生成类请求的非敏感摘要，例如文本长度、音频时长、文件大小、模型 ID。
不要把完整 API Token、完整用户音频 URL 或隐私文本发送到公开渠道。
客户端类型建议
SDK 可把错误统一解析为：
type KittaApiError = {
status: number;
code?: string;
message: string;
requestId?: string;
details?: Record<string, unknown>;
};解析时把 response.error 展平为 SDK 错误对象，同时保留未知字段。这样服务端扩展 supportedModels 或其它诊断字段时，客户端不会丢失信息。