错误参考

了解 BringSkills 的错误返回结构、重试行为和限流规则。

HTTP 状态码

标准错误格式

常见错误类型

处理最佳实践

标准错误格式

大多数 API 失败请求都会返回统一的 JSON 结构，便于你排错、告警和记录日志。

{
  "code": 400,
  "message": "Invalid request: missing required field 'input'",
  "error_type": "validation_error",
  "details": {
    "field": "input",
    "reason": "required"
  },
  "request_id": "req_abc123xyz"
}

HTTP 状态码

2xx 成功

200OK— 请求成功

201Created— 资源创建成功

4xx 客户端错误

400Bad Request— 请求格式或参数不正确

401Unauthorized— 缺少或使用了无效 API Token

403Forbidden— Token 有效但权限不足

404Not Found— 请求的资源不存在

409Conflict— 资源已存在或当前状态不允许该操作

422Unprocessable— 校验未通过

429Too Many Requests— 已触发请求频率限制

5xx 服务端错误

500Internal Error— 出现未预期的服务端错误

502Bad Gateway— 上游服务暂时不可用

503Service Unavailable— 服务暂时不可用

504Gateway Timeout— 上游服务响应超时

常见错误类型

authentication_error

缺少 Token 或 Token 无效

确认 Token 存在、未过期，并且属于当前要调用的环境

authorization_error

Token 权限不足

确认技能已进入你的库，并且所用 key 属于正确账户

validation_error

请求数据未通过校验

检查必填字段、数据类型以及嵌套输入字段名

not_found_error

请求的资源不存在

核对 skill slug、key ID 或接口路径是否正确

rate_limit_error

短时间内请求过多

使用指数退避，并遵循响应头里的重试提示

execution_error

通过校验后，技能执行阶段仍然失败

检查输入载荷，必要时缩小请求规模并改正参数后重试

internal_error

平台内部或依赖侧出现错误

稍后重试；如需联系支持，请带上 request_id

错误类型	含义	建议处理方式
`authentication_error`	缺少 Token 或 Token 无效	确认 Token 存在、未过期，并且属于当前要调用的环境
`authorization_error`	Token 权限不足	确认技能已进入你的库，并且所用 key 属于正确账户
`validation_error`	请求数据未通过校验	检查必填字段、数据类型以及嵌套输入字段名
`not_found_error`	请求的资源不存在	核对 skill slug、key ID 或接口路径是否正确
`rate_limit_error`	短时间内请求过多	使用指数退避，并遵循响应头里的重试提示
`execution_error`	通过校验后，技能执行阶段仍然失败	检查输入载荷，必要时缩小请求规模并改正参数后重试
`internal_error`	平台内部或依赖侧出现错误	稍后重试；如需联系支持，请带上 request_id

高频错误场景

Token 无效或已过期

401

{
  "code": 401,
  "message": "Invalid or expired API token",
  "error_type": "authentication_error"
}

修复建议：如果当前 key 被删除、轮换或暴露过，请重新生成一个新的 API 密钥。

技能不在你的技能库中

403

{
  "code": 403,
  "message": "You have not purchased this skill",
  "error_type": "authorization_error",
  "details": {
    "skill_slug": "premium-analyzer"
  }
}

修复建议：先领取免费技能或完成购买，再调用执行接口。

输入校验失败

422

{
  "code": 422,
  "message": "Validation failed",
  "error_type": "validation_error",
  "details": {
    "errors": [
      {"field": "input.text", "message": "Required field missing"}
    ]
  }
}

修复建议：对照技能的输入 schema 检查请求体，确保所有必填字段都已传入。

请求频率超限

429

{
  "code": 429,
  "message": "Rate limit exceeded",
  "error_type": "rate_limit_error",
  "details": {
    "limit": 100,
    "window": "1m",
    "retry_after": 45
  }
}

修复建议：先退避等待，再重试，并避免同一个 key 出现大规模并发突发请求。

处理最佳实践

永远检查非 2xx 响应

抛错前先解析响应体，这样你才能拿到真正的 API 错误信息。

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`API Error: ${error.message}`);
}

const data = await response.json();

只在适合时重试

429 和 5xx 适合退避重试，但格式错误的请求不应该盲目重放。

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.ok) return response.json();
    
    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    
    throw new Error(`API Error: ${response.status}`);
  }
  throw new Error('Max retries exceeded');
}

记录 request_id

把请求 ID 写入日志和支持工单，后续定位问题会快很多。

try {
  const result = await executeSkill(input);
} catch (error) {
  console.error('Skill execution failed', {
    message: error instanceof Error ? error.message : 'Unknown error',
    request_id: error && typeof error === 'object' && 'request_id' in error ? error.request_id : null, // Include in support tickets
    timestamp: new Date().toISOString()
  });
}

限流说明

免费 / 入门用量

100

次请求 / 分钟

付费 / 生产用量

1,000

次请求 / 分钟

企业级

定制

联系销售

限流响应头

当收到 429 时，优先读取 Retry-After 等响应头，再决定下一次重试时间。

返回：支持的 AI 助手下一步：接入指南

标准错误格式

大多数 API 失败请求都会返回统一的 JSON 结构，便于你排错、告警和记录日志。

{
  "code": 400,
  "message": "Invalid request: missing required field 'input'",
  "error_type": "validation_error",
  "details": {
    "field": "input",
    "reason": "required"
  },
  "request_id": "req_abc123xyz"
}

HTTP 状态码

2xx 成功

200OK— 请求成功

201Created— 资源创建成功

4xx 客户端错误

400Bad Request— 请求格式或参数不正确

401Unauthorized— 缺少或使用了无效 API Token

403Forbidden— Token 有效但权限不足

404Not Found— 请求的资源不存在

409Conflict— 资源已存在或当前状态不允许该操作

422Unprocessable— 校验未通过

429Too Many Requests— 已触发请求频率限制

5xx 服务端错误

500Internal Error— 出现未预期的服务端错误

502Bad Gateway— 上游服务暂时不可用

503Service Unavailable— 服务暂时不可用

504Gateway Timeout— 上游服务响应超时

常见错误类型

authentication_error

缺少 Token 或 Token 无效

确认 Token 存在、未过期，并且属于当前要调用的环境

authorization_error

Token 权限不足

确认技能已进入你的库，并且所用 key 属于正确账户

validation_error

请求数据未通过校验

检查必填字段、数据类型以及嵌套输入字段名

not_found_error

请求的资源不存在

核对 skill slug、key ID 或接口路径是否正确

rate_limit_error

短时间内请求过多

使用指数退避，并遵循响应头里的重试提示

execution_error

通过校验后，技能执行阶段仍然失败

检查输入载荷，必要时缩小请求规模并改正参数后重试

internal_error

平台内部或依赖侧出现错误

稍后重试；如需联系支持，请带上 request_id

错误类型	含义	建议处理方式
`authentication_error`	缺少 Token 或 Token 无效	确认 Token 存在、未过期，并且属于当前要调用的环境
`authorization_error`	Token 权限不足	确认技能已进入你的库，并且所用 key 属于正确账户
`validation_error`	请求数据未通过校验	检查必填字段、数据类型以及嵌套输入字段名
`not_found_error`	请求的资源不存在	核对 skill slug、key ID 或接口路径是否正确
`rate_limit_error`	短时间内请求过多	使用指数退避，并遵循响应头里的重试提示
`execution_error`	通过校验后，技能执行阶段仍然失败	检查输入载荷，必要时缩小请求规模并改正参数后重试
`internal_error`	平台内部或依赖侧出现错误	稍后重试；如需联系支持，请带上 request_id

高频错误场景

Token 无效或已过期

401

{
  "code": 401,
  "message": "Invalid or expired API token",
  "error_type": "authentication_error"
}

修复建议：如果当前 key 被删除、轮换或暴露过，请重新生成一个新的 API 密钥。

技能不在你的技能库中

403

{
  "code": 403,
  "message": "You have not purchased this skill",
  "error_type": "authorization_error",
  "details": {
    "skill_slug": "premium-analyzer"
  }
}

修复建议：先领取免费技能或完成购买，再调用执行接口。

输入校验失败

422

{
  "code": 422,
  "message": "Validation failed",
  "error_type": "validation_error",
  "details": {
    "errors": [
      {"field": "input.text", "message": "Required field missing"}
    ]
  }
}

修复建议：对照技能的输入 schema 检查请求体，确保所有必填字段都已传入。

请求频率超限

429

{
  "code": 429,
  "message": "Rate limit exceeded",
  "error_type": "rate_limit_error",
  "details": {
    "limit": 100,
    "window": "1m",
    "retry_after": 45
  }
}

修复建议：先退避等待，再重试，并避免同一个 key 出现大规模并发突发请求。

处理最佳实践

永远检查非 2xx 响应

抛错前先解析响应体，这样你才能拿到真正的 API 错误信息。

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`API Error: ${error.message}`);
}

const data = await response.json();

只在适合时重试

429 和 5xx 适合退避重试，但格式错误的请求不应该盲目重放。

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.ok) return response.json();
    
    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    
    throw new Error(`API Error: ${response.status}`);
  }
  throw new Error('Max retries exceeded');
}

记录 request_id

把请求 ID 写入日志和支持工单，后续定位问题会快很多。

try {
  const result = await executeSkill(input);
} catch (error) {
  console.error('Skill execution failed', {
    message: error instanceof Error ? error.message : 'Unknown error',
    request_id: error && typeof error === 'object' && 'request_id' in error ? error.request_id : null, // Include in support tickets
    timestamp: new Date().toISOString()
  });
}