错误码参考

完整的 Agent 服务错误码列表和说明，帮助你快速定位和解决问题。

错误响应格式

{
  "status": 错误码,
  "msg": "错误描述",
  "result": null,
  "request_id": "req_..."
}

Agent 错误码 (200-399)

与 Agent 业务逻辑相关的错误。

参数错误 (200-209)

代码	说明	解决方案
203	必填参数为空	检查请求参数，补充缺失的必填字段
204	参数格式错误	检查参数类型和格式是否正确

工具错误 (300-309)

代码	说明	解决方案
301	工具 ID 不存在	检查 tool_id 是否正确，或查看可用接口列表
302	工具参数缺失或格式错误	检查工具所需参数，确保参数完整且格式正确
303	搜索查询为空	提供有效的搜索查询字符串
304	未找到匹配的工具	尝试更换搜索关键词或查看可用接口列表

权限错误 (400-409)

代码	说明	解决方案
401	需要实名认证	前往会员中心完成实名认证
402	需要企业认证	前往会员中心完成企业认证

上游错误 (500-509)

代码	说明	解决方案
501	上游超时	稍后重试，或联系客服
502	上游错误	上游接口返回错误，查看 msg 详情

系统错误码 (100-199)

与系统认证、权限、限流等相关的错误。

认证错误 (100-109)

代码	说明	解决方案
101	APPKEY 为空或不存在	检查 Authorization Header 是否正确设置
102	APPKEY 已过期	前往会员中心续费或更换 APPKEY
103	APPKEY 无请求此数据权限	检查是否已开通该接口权限
104	请求超过次数限制	检查套餐余额，或前往会员中心充值

IP 限制 (105-109)

代码	说明	解决方案
105	IP 被禁止	联系客服解封
106	IP 请求超过限制	降低请求频率，或联系客服提高限制

故障排查指南

认证相关

问题：收到 101 错误

检查清单：

• Authorization Header 格式：Authorization: Bearer your_appkey
• APPKEY 前后是否有空格
• 是否使用了正确的 APPKEY

问题：收到 102 错误

解决方案：

• 登录会员中心检查 APPKEY 状态
• 充值续费或更换新的 APPKEY

工具相关

问题：收到 301 错误

可能原因：

• tool_id 拼写错误
• 该工具已下线
• 该工具暂不支持 Agent 调用

解决方案：

• 查看Agent 可用接口列表确认正确的 tool_id
• 使用 search 接口搜索相似功能的工具

问题：收到 302 错误

解决方案：

• 查看接口文档，确认所需参数
• 检查参数类型（字符串、数字、布尔值等）
• 确保必填参数都已提供

限流相关

问题：收到 106 错误

临时解决：

• 降低请求频率
• 实现请求队列和重试机制
• 使用多个 IP 分散请求

长期解决：

• 联系客服提高频率限制
• 升级套餐获得更高限额

重试策略建议

可重试的错误

以下错误建议实现自动重试：

• 501 - 上游超时（建议重试 2-3 次）
• 502 - 上游错误（建议重试 1 次）
• 106 - 请求限制（建议延迟后重试）

不可重试的错误

以下错误不应重试，需要修正请求：

• 101-105 - 认证和权限错误
• 203-204 - 参数错误
• 301-304 - 工具错误

重试示例代码

import time
import requests

def call_agent_api(url, data, max_retries=3):
    retries = 0
    while retries < max_retries:
        try:
            response = requests.post(url, json=data, headers=headers)
            result = response.json()
            
            # 成功返回
            if result['status'] == 0:
                return result
            
            # 可重试错误
            if result['status'] in [501, 502, 106]:
                retries += 1
                time.sleep(2 ** retries)  # 指数退避
                continue
            
            # 不可重试错误
            return result
            
        except requests.exceptions.RequestException as e:
            retries += 1
            if retries >= max_retries:
                raise
            time.sleep(2 ** retries)
    
    return {"status": -1, "msg": "重试次数耗尽"}

获取帮助

如果遇到文档中未列出的错误码，或需要进一步帮助：

• 记录 request_id 和错误详情
• 联系客服微信
• 发送邮件至 kf@jisuapi.com