文档中心

大模型应用防火墙

API 参考

错误码说明

本文介绍大模型应用防火墙接口调用失败或检测未按预期执行时，常见返回信息的含义和排查方法。

接口返回异常时，建议先按以下顺序定位：

根据 HTTP 响应码，判断请求是否通过接口参数和鉴权校验。

HTTP 响应码为 200 时，继续检查返回体中的 Degraded、DegradeReason 和 Decision；其他响应码查看错误码和错误信息。

按照处理建议检查参数、资产、鉴权、实例状态或检测内容。

返回类型说明

返回类型	含义	常见处理方式
HTTP 400	请求未通过接口参数校验或鉴权校验。	优先检查 Action、Version、AppID、签名、Region、AK/SK。
HTTP 200	接口请求已成功到达并得到业务响应，检测可能正常完成，也可能发生降级。	检查 Degraded。如果为 true，继续查看 DegradeReason 和 Decision，并根据原因决定重试、阻断或人工复核。

错误码详解

HTTP 400 请求异常

错误码	错误信息	可能原因	处理建议
InvalidParameter	The specified parameter Action is invalid.	Action 参数无效。	检查接口名称是否正确，确保 Action 与实际调用接口一致。
		The specified parameter Version is invalid.	Version 参数无效。	检查接口版本是否正确，确保 Version 与接口文档要求一致。
		The specified parameter BodyNoAppID is invalid.	请求中缺少有效 AppID，或 AppID 格式错误。	前往控制台确认资产 AppID，并检查请求体中是否正确传入。
		The specified parameter NotMatchAccessmode is invalid.	填入的 AppID 对应资产不是 SDK 接入资产。	确认当前接口调用使用的是 SDK 接入资产；如资产为流量接入，请更换为正确的 SDK 接入资产 AppID。
AuthCheckFailed	SignatureResErr、SignatureNoMatch、AuthSignatureExcept、CheckPolicyLocal、AuthByPassError	鉴权失败，通常与签名、AK/SK、Region 或请求地址有关。	检查 AK/SK 是否正确、Region 与请求地址是否匹配、签名计算是否符合要求。可先使用官方 SDK 示例验证鉴权是否正常。
Resource.NotExist	The specified resource does not exist. Please check NotFoundApp and try again.	AppID 对应资产不存在、已删除，或未接入当前防护实例。	前往控制台确认资产是否存在、是否已接入大模型应用防火墙实例，并核对 AppID 是否填写正确。
Resource.QuotaExceeded	资源容量已达上限。请检查 AppCap 再尝试操作。	资源管理操作中，当前实例的证书、自定义拦截响应规则或其他受配额管理的资源已达到上限。	删除不再使用的资源后重试，并在控制台核对实例配额。证书数量上限与实例资产配额一致；自定义拦截响应规则总数上限为实例资产配额的 100 倍。如需更高配额，请联系技术支持。

HTTP 200 请求降级

说明

HTTP 响应码为 200 仅表示接口请求成功到达服务端，不代表检测和后续处理一定完整完成。Degraded=true 表示至少一项预期检测或后续处理未完整完成，DegradeReason 中的多个原因可能使用 | 连接。降级请求通常返回 PASS，但最终处置仍应以 Decision 为准；不要将降级响应中的 PASS 理解为内容已确认安全。

常见处置	降级原因	可能原因	处理建议
通常为 PASS，以 Decision 为准	NotFoundApp 或 USER-AppNotProtected	未找到有效资产，AppID 不存在、未接入或未启用防护。	前往控制台确认资产 AppID 是否存在、是否填写准确、是否已接入防护实例并启用防护。
		REQUEST_ERROR_DEGRADE: empty message content	送检消息为空。	检查 message 或送检内容字段，确保传入非空文本、文件、图片、音频或视频内容。
		SYS-QPSLimit	请求超过 QPS 限流阈值。	降低调用频率，增加重试间隔；如业务需要更高并发，请评估实例规格或联系技术支持。
		SYS-CheckTradeTypeNotSupport	当前资产或策略不支持本次送检内容类型。	检查资产对应的防护策略是否已配置该检测类型，例如文本、图片、文件、音频或视频。
		SYS-ContentTypeDisable_TEXT、SYS-ContentTypeDisable_AUDIO、SYS-ContentTypeDisable_IMAGE、SYS-ContentTypeDisable_VIDEO 或 SYS-ContentTypeDisable_FILE	当前资产未启用对应内容类型的检测。	在资产和防护配置中启用对应内容类型，或改用资产当前支持的内容类型。
		NotMatchAccessmode 或 SYS-AppNotMatch	资产接入方式与调用方式不匹配，或请求资产与当前凭证不匹配。	检查资产是 SDK 接入还是流量接入，并核对账号、调用方式和 AppID。
		USER-InvalidMessage	message 为空或格式不符合要求。	检查 message 结构、角色字段、内容字段和多模态内容格式是否符合 SDK 或接口要求。
		SYS-InstanceNotActive	实例到期、未激活或状态异常。	前往控制台确认实例状态；如实例已到期，请续费或重新激活。
		SYS-TimeoutOrCancel 或 SYS-NotEnoughRemainingTime	检测超时、请求被取消，或剩余时间不足以完成检测。	检查内容大小和客户端超时设置；适当延长超时，或拆分过大的文档、视频和多模态请求后重试。
		SYS-PreTaskAbnormal、SYS-PreTaskContentNil 或 SYS-PreTaskContentInvalid	内容预处理异常，未生成可检测内容。	检查内容是否为空、编码和格式是否有效，修正后重新请求。
		SYS-GetImageTicketError、SYS-GetFileTicketError 或 SYS-FileTaskAllFailed	图片或文档检测任务调度失败，或文档中的内容均未完成检测。	减小单次请求规模并稍后重试；持续发生时保留 RequestID 和时间范围并联系技术支持。
		SYS-ServerReturnNil 或 SYS-ServerDegraded	检测服务未返回结果或主动降级。	稍后重试，并使用 RequestID 关联日志；持续发生时联系技术支持。
可能为 OPTIMIZE	SYS-GenerateExcept，可能与 SYS-QPSLimit 同时出现	检测触发安全代答，但代答生成失败或被限流。	检查 MsgID、代答调用频率和超时设置，并在使用代答前确认替换内容非空。
以 Decision 为准	其他异常	送检消息处理异常，可能包括文件过大、URL 下载失败、解码失败、超时或服务内部处理错误。	检查送检内容大小、URL 可访问性、文件格式、网络连通性和超时时间；如问题持续出现，请保留 RequestID 并提交工单。

常见排查路径

参数类问题

如果返回 InvalidParameter、Action invalid 或 Version invalid，通常是接口参数填写错误。请重点检查：

Action 是否为接口实际名称。

Version 是否为接口文档要求的版本。

请求体是否符合接口格式。

SDK 版本是否支持当前接口。

鉴权类问题

如果返回 AuthCheckFailed、SignatureNoMatch 或类似签名错误，请重点检查：

AK/SK 是否正确，是否已过期或被禁用。

请求使用的 Region 是否与服务地址一致。

系统时间是否准确，避免签名时间偏差过大。

自行生成签名时，签名算法、Header、Query 和 Body 是否与《API签名生成规范》文档一致。

建议优先使用官方 SDK 示例验证 AK/SK 和 Region 是否可用，再排查自定义签名逻辑。

资产类问题

如果返回 Resource.NotExist 或 NotFoundApp，请重点检查：

AppID 是否填写正确。

资产是否已接入当前防护实例。

资产是否被删除或停用。

当前调用账号是否有权限访问该资产。

接入方式不匹配

如果返回 NotMatchAccessmode，说明调用方式和资产接入方式不一致。例如：

使用 SDK 接口调用时，传入了流量接入资产的 AppID。

使用流量接入方式访问时，使用了 SDK 接入资产配置。

请在控制台确认资产接入方式，并选择匹配的调用方式。

送检内容问题

如果返回 empty message content 或 USER-InvalidMessage，请检查：

message 是否为空。

文本内容是否为空字符串。

多模态内容是否包含有效的 ContentType 和内容地址/内容 ID。

Role、Content、MultiPart 等字段是否符合 SDK 要求。

实例和限流问题

如果返回 SYS-QPSLimit 或 SYS-InstanceNotActive，请检查：

当前请求是否超过实例 QPS 限制。

实例是否到期、欠费、未激活或状态异常。

是否需要调整调用重试策略或升级实例规格。

最近更新时间：2026.10.22 21:32:36

这个页面对您有帮助吗？

有用

无用