API 返回 403 或 404 怎么查？

更新于 2026-10-27 · openox.cyou

简答：先用 curl -i 或 curl -v 复现一次，保存完整 URL、HTTP 方法、响应头、响应体和 request ID。403 通常优先检查认证后的权限、API Key、模型或项目权限、IP/WAF 与网关策略；404 则优先核对域名、端口、Base URL、版本前缀、资源路径、资源 ID 和部署环境。需要注意，部分网关会用 404 隐藏无权访问的资源，因此不能只看状态码下结论。

定义：API 403 表示服务器理解请求但拒绝授予访问权限，API 404 表示服务器找不到请求的资源，但在安全策略下也可能被用来隐藏资源是否存在。

先做最小复现：保存请求和响应，不要反复重试

API 返回 403 或 404 时，第一步不是更换模型或连续重试，而是把一次失败请求固定下来。至少记录 HTTP 方法、完整 URL、请求头、请求体、响应头、响应体、时间和 request ID。如果响应来自 API 网关或反向代理，响应头中的服务标识、追踪 ID 和缓存信息，往往比客户端报错文本更有用。

可以先用下面的通用模板复现。API_URL、HTTP_METHOD 和请求体必须替换为服务商当前文档中确认过的值；不要把示例域名、路径或模型名直接当作真实接口使用。

export API_URL='https://按服务商文档填写的实际地址'
export HTTP_METHOD='GET'

curl -i -v --request "$HTTP_METHOD" "$API_URL" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Accept: application/json'

如果是 JSON POST 请求，再按接口文档补充 Content-Type 和请求体：

curl -i -v --request POST "$API_URL" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"model":"按服务商文档填写","input":"test"}'

排查时不要在命令行、截图或工单中直接贴出完整 Key。可以只检查变量是否存在：

if [ -n "$API_KEY" ]; then echo 'API_KEY is set'; else echo 'API_KEY is missing'; fi

以上命令只负责观察实际响应，不预设某个供应商的固定 Base URL、/v1 路径或鉴权格式。具体端点、路径和请求字段应以当前服务商 API 文档为准。

403 和 404 到底有什么区别？先按状态码分流

按照 HTTP 的标准定义，403 表示服务器理解了请求，但拒绝授予访问权限；404 表示服务器找不到请求的资源。MDN 还特别指出，服务器可能用 404 代替 403，以隐藏受保护资源是否存在，所以“返回 404 就一定是路径错”并不成立。可参考 MDN 对 403 的说明、MDN 对 404 的说明。

状态码	标准含义	优先怀疑的位置	下一步
401	缺少或没有通过认证	客户端鉴权	检查 Authorization、API Key 格式、过期状态和认证方案；同时查看是否有 WWW-Authenticate 响应头。
403	已识别请求，但拒绝访问	权限、网关、WAF、来源限制	检查项目、角色、Scope、模型权限、API Key 状态、IP 白名单、WAF 和网关策略。
404	找不到资源	URL、路由、资源 ID 或安全隐藏策略	核对域名、端口、Base URL、版本前缀、路径、大小写、尾部斜杠、部署环境和资源是否已发布。
405	路径存在，但不支持当前 HTTP 方法	客户端请求方法或路由配置	检查接口定义和响应中的 Allow 头，确认 GET、POST、DELETE 等方法是否用对。

401 与 403 不应混为一谈：401 主要表示身份认证未通过，403 则通常表示身份已被识别但没有执行该操作的权限。405 也不是“接口不存在”，而是服务器识别了资源，却不接受当前方法；相关定义可参阅 MDN 的 401 说明和 MDN 的 405 说明。

403 排查顺序：先确认 Key，再查权限和入口策略

确认请求确实带上了认证信息。检查实际发送的请求头是否包含服务商要求的 Authorization、x-api-key 或其他鉴权字段。不同 API 的认证方式不一定相同，不要把 Bearer Token、普通 API Key 和签名请求混用。
检查 Key 是否有效且未被禁用。核对是否复制了多余空格、换行或错误的环境变量；同时确认 Key 所属账户、项目和环境与当前接口一致。
检查调用权限。重点看账户角色、项目 Scope、模型权限、组织或租户限制，以及该 Key 是否允许当前操作。403 的核心不是“接口有没有响应”，而是“当前身份能否执行这个操作”。
检查来源和网络策略。如果服务启用了 IP 白名单、来源域名限制、私有网络、mTLS 或 WAF，换一台机器测试并不能自动解决问题；应查看网关、WAF 或服务端日志中的命中规则。AWS API Gateway 的官方排查资料列出了无效 API Key、IAM 或资源策略拒绝、WAF、私有 API 入口、错误 stage 和自定义域名映射等多种 403 来源，可参考 AWS API Gateway 403 排查说明。
检查网关路由和发布状态。对于自建网关或反向代理，要确认路由配置已发布，方法、路径和环境映射一致；如果请求没有出现在后端日志中，问题更可能发生在客户端、CDN/WAF 或网关层。
根据响应头和 request ID 查日志。不要只看客户端显示的“Forbidden”。把响应中的 request ID、时间戳、Host 和路径交给服务端管理员，在网关访问日志、WAF 日志和后端日志中逐层查找。

403 也可能是 API 网关返回的统一错误，而不是模型服务本身返回的错误。例如 AWS 文档将授权失败、无效签名、缺少认证令牌和 WAF 拦截都列为可能产生 403 的网关响应类型。具体字段和响应文本仍应以当前平台文档为准。

404 排查顺序：从域名和 Base URL 查到资源 ID

核对协议、域名和端口。确认请求没有误用管理端点、登录端点、旧域名或内部域名。用 nslookup 或 dig 查看域名解析结果，并确认请求实际到达预期入口。
核对 Base URL 和版本前缀。逐字符比较服务商文档中的 Base URL、/v1 或其他版本路径。不要根据其他平台的习惯自行添加或删除版本前缀。
核对资源路径和大小写。检查路径拼写、大小写、尾部斜杠、URL 编码、查询参数和资源 ID。API 中的模型 ID、项目 ID、部署 ID 和版本 ID 可能不是同一个概念。
核对环境和发布状态。开发、测试、生产环境可能使用不同域名、路由前缀或资源 ID。自建 API 网关还要确认路由已经部署到当前 stage；AWS 的官方资料也建议确认 API 定义已部署且请求资源确实存在。
确认 HTTP 方法与路径组合。同一个路径可能只支持 GET 或 POST。若路径存在但方法不对，规范上更接近 405；不过部分网关会返回统一的 404 或 403，因此仍要对照接口定义和网关日志。
检查是否存在“安全隐藏”。如果公开请求返回 404，而已授权请求返回 200，或错误响应明确提示权限不足，那么 404 可能是平台有意隐藏资源存在性。此时应回到 Key、项目权限和资源授权检查，而不是盲目改路径。

如果你能控制网关，建议同时查看网关访问日志和后端访问日志：网关有记录、后端没有记录，通常说明路由、鉴权或策略在网关层结束；两边都有记录，则继续检查后端资源 ID、版本和业务权限。Azure API Management 的官方诊断入口也将网关性能、API 策略和 4xx/5xx 请求作为独立排查类别，可参考 Azure API Management 故障排查总览。

如何判断错误来自客户端、CDN/WAF、网关还是后端？

观察点	客户端或网络层	CDN/WAF	API 网关	后端服务
后端日志	通常没有请求	通常没有请求	可能没有转发	能找到对应请求
响应特征	连接失败、DNS 或 TLS 错误	带有 WAF/CDN 标识或拦截信息	有网关 request ID、统一错误 JSON 或网关响应头	包含业务错误、模型或资源相关信息
最有价值的证据	curl -v、DNS、代理配置	WAF 命中规则、边缘日志、缓存头	路由、鉴权、策略和访问日志	应用日志、资源状态、链路追踪
处理方向	修正 URL、代理、证书或请求格式	核对 IP、来源、规则和缓存	修正 Base URL、stage、映射、Key 或权限	修正资源 ID、业务权限或后端路由

最可靠的判断方法是把同一个请求的客户端时间、request ID、Host、路径和状态码串起来，再分别查边缘、网关和后端日志。仅凭响应体中的一行“Not Found”或“Forbidden”，通常不足以确定故障层级。

一份可执行的 10 分钟自查清单

确认使用的是当前服务商文档中的域名、协议、端口、Base URL 和 API 版本。
用 curl -i -v 发送一次最小请求，保存响应头和响应体。
确认 HTTP 方法与接口定义一致，并检查 Content-Type、Accept 和请求体格式。
确认 API Key 或 Authorization 变量存在，且没有多余空格、换行或错误前缀。
如果是 403，检查账户、项目、角色、Scope、模型权限、Key 状态、IP 白名单和 WAF。
如果是 404，逐字符核对域名、Base URL、版本前缀、路径、资源 ID、大小写、尾部斜杠和环境。
检查响应头中的 request ID、服务标识、缓存信息和安全策略提示。
确认请求是否出现在 API 网关日志中，再确认是否到达后端日志。
如果改过网关、路由或 API 定义，确认配置已发布到当前环境。
将脱敏后的方法、路径、状态码、响应头、request ID 和时间交给服务提供方定位，不要提交完整 Key。

如果错误在本地命令行中出现，但客户端工具中没有出现，优先比较两边的完整 URL、HTTP 方法、鉴权头和代理设置；如果两边都出现同样状态码，再把重点转向网关和服务端日志。

说明：本文为独立技术整理，页面不代表任何 API 平台或模型服务的官方文档；接口字段、域名、权限和状态码表现应以实际服务商当前文档为准。

常见问题

API 返回 403，是不是 API Key 一定错了？

不一定。403 也可能来自项目或模型权限不足、Key 已被禁用、IP 白名单、WAF、API 网关策略、错误 stage、自定义域名映射或私有入口限制。先查看响应头、错误 JSON 和 request ID，再查对应平台日志。

API 返回 404，应该先改 Base URL 还是改模型名？

通常先核对域名、端口、Base URL、版本前缀和资源路径，再检查模型名或其他资源 ID。模型名错误可能属于资源不存在，但如果整个路径或版本前缀错误，修改模型名不会解决问题。

为什么没有 Authorization 也可能返回 404，而不是 401？

服务器或网关可能用 404 隐藏受保护资源是否存在，避免向未授权请求暴露资源信息。MDN 明确说明，服务器可以用 404 代替 403；因此要结合已授权请求、响应头和网关日志判断。

curl -i 和 curl -v 分别有什么用？

curl -i 会把响应头与响应体一起显示，适合查看状态码、request ID 和服务标识；curl -v 还会显示 DNS、连接、TLS、请求头和响应头等通信细节，适合判断请求是否到达了预期域名或代理。两者都不应把完整 Key 粘贴到公开日志。

403 和 404 都能访问域名，说明 DNS 没问题吗？

只能说明请求可能到达了某个 HTTP 服务，不能证明到达了正确的 API 网关或后端。仍需核对 Host、响应头、网关标识、路由映射和 request ID；错误域名也可能返回一个统一的 403 或 404 页面。

参考资料

MDN：403 Forbidden - HTTP
MDN：404 Not Found - HTTP
MDN：401 Unauthorized - HTTP
MDN：405 Method Not Allowed - HTTP
AWS re:Post：Troubleshoot HTTP 403 errors from API Gateway（repost.aws）
AWS re:Post：Resolve API Gateway REST API 403 Missing Authentication Token errors（repost.aws）
Microsoft Learn：Troubleshoot common issues with Azure API Management