错误处理

了解 Alaya Code API 的错误码和推荐的处理方式。

错误响应格式

当 API 请求失败时，响应体包含以下格式的错误信息：

{
  "error": {
    "message": "Error description",
    "type": "error_type",
    "code": "error_code"
  }
}

错误码列表

状态码	状态	说明	常见原因	处理方式
400	Bad Request	请求格式错误	请求体 JSON 格式错误或缺少必需字段（如 `model`、`messages`）	检查请求体格式是否正确，确保必需字段完整
401	Unauthorized	认证失败	API Key 无效、过期或未提供	检查 Authorization Header 格式和 API Key 是否正确
402	Payment Required	额度不足	账户余额不足或已达到月消费上限	升级套餐或购买加油包补充额度
403	Forbidden	权限不足	当前套餐不支持请求的模型或功能	升级到支持该模型的套餐
404	Not Found	资源不存在	请求的接口路径或模型名称不存在	检查 URL 路径和模型名称是否正确
429	Too Many Requests	请求频率过高	超过套餐的 RPM 或 TPM 限制	降低请求频率或升级套餐。响应头中包含 `Retry-After` 字段
500	Internal Server Error	服务器内部错误	服务端异常	重试请求。如果持续出现，请联系技术支持
502	Bad Gateway	上游服务异常	模型提供商的 API 暂时不可用	稍后重试，或切换到其他模型
503	Service Unavailable	服务暂时不可用	系统维护或过载	稍后重试

重试策略

对于 429 和 5xx 错误，建议实现指数退避重试：

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

常见排查步骤

确认 API Key 正确：在控制台检查 Key 是否处于启用状态，复制 Key 时注意不要多余的空格。
检查 Base URL：确保 URL 为 https://codingplan.alayanew.com/v1（注意末尾的 /v1）。
检查模型名称：使用 GET /v1/models 接口查看当前可用的模型列表。
检查额度：在控制台的用量统计页面查看当前窗口的额度使用情况。

错误响应格式

错误码列表

重试策略

常见排查步骤

目录