语义化 HTTP 状态码
云开发网关按错误场景返回 HTTP 状态码，同一状态码下的错误码对应相同的处理方式。本页列出的状态码均为 4XX，可在自定义错误页中配置专属错误页。
下文各状态码仅列出典型错误码，完整错误码列表参考错误码概述。
总览
| HTTP 状态码 | 场景语义 | 建议操作 |
|---|---|---|
| 401 | 鉴权失败：凭证缺失、无效或过期 | 检查或更新凭证，重新登录 |
| 402 | 欠费、超套餐或资源隔离 | 充值、升级套餐或调整用量 |
| 403 | 权限不足或访问策略拒绝 | 检查权限与访问策略配置 |
| 404 | 资源不存在 | 确认资源、域名、路径是否已创建 |
| 423 | 功能未启用或路由被禁用 | 前往控制台开启对应功能或检查路由配置 |
| 429 | 频率、配额或并发超限 | 降低请求频率或升级配额 |
| 451 | 封禁或合规拦截 | 检查内容合规性 |
401 Unauthorized
鉴权失败，凭证缺失、无效或已过期。检查请求中的凭证，必要时重新登录后再发起请求。
| 错误码 | 说明 |
|---|---|
| MISSING_CREDENTIALS | 请求头中缺少必要的身份鉴权信息 |
| INVALID_CREDENTIALS | 身份认证失败，用户信息校验失败 |
| ACCESS_TOKEN_INVALID | 请求头中身份认证信息无效 |
| ACCESS_TOKEN_EXPIRED | access token 已过期 |
| ACCESS_TOKEN_KID_INVALID | 访问令牌的 Key ID (kid) 无效 |
| AUTHENTICATION_FAILED | 请求鉴权失败 |
402 Payment Required
资源因欠费、超出套餐或被隔离而停用。充值、升级套餐或调整用量后恢复。
| 错误码 | 说明 |
|---|---|
| ENV_SUSPENDED | 环境已停服，请检查环境用量是否超出套餐限制 |
| ENV_ISOLATED | 环境已到期隔离，续费后恢复 |
| DATABASE_RESOURCE_ISOLATED | 数据库资源已隔离 |
| SERVICE_CHARGE_OVERDUE | 欠费停机，请及时充值 |
403 Forbidden
权限不足或被访问策略拒绝。检查安全规则、来源限制等权限与策略配置。
| 错误码 | 说明 |
|---|---|
| ACCESS_DENIED | 请求被网关策略拒绝 |
| ACTION_FORBIDDEN | 当前身份无权限执行该操作 |
| EXCEED_AUTHORITY | 超出权限范围 |
| STORAGE_EXCEED_AUTHORITY | 当前用户无权限操作云存储资源 |
| OBJECT_BATCH_TOO_LARGE | 单次批量操作的对象数量过多 |
| FUNCTIONS_PERMISSION_DENIED | 无权限调用该云函数 |
| AI_MODEL_NOT_SUPPORTED | 不支持的具体模型 |
| AI_CHANNEL_NOT_ALLOWED | 小程序成长计划仅支持小程序 SDK 和云开发 SDK 调用 |
| SERVICE_FORBIDDEN | 服务被禁用，可能是权限关闭、环境异常或微信云托管启动中 |
| DEFAULT_DOMAIN_EXPIRED | 默认域名已超过使用有效期，需要续期或绑定自定义域名 |
| CDN_SIGNATURE_MISSING | 当前访问链接的签名缺失 |
| CDN_INVALID_SIGNATURE | 当前访问链接的签名不正确 |
| CDN_SIGNATURE_EXPIRED | 当前访问链接的签名已过期 |
404 Not Found
资源不存在。确认资源、域名、路径是否已创建或配置正确。
| 错误码 | 说明 |
|---|---|
| INVALID_HOST | 非法的主机 |
| INVALID_REGION | 非法的地域 |
| INVALID_PATH | 未找到匹配的转发规则，请检查 HTTP 网关的转发规则配置 |
| INVALID_ENV | 错误的环境、环境未找到 |
| FUNCTIONS_NOT_FOUND | 云函数未找到 |
| FUNCTIONS_NAME_MISSING | 调用时未指定函数名 |
| FUNCTIONS_QUALIFIER_NOT_FOUND | 指定访问的函数版本不存在 |
| SERVICE_NOT_FOUND | 未找到对应的云托管服务 |
| SERVICE_VERSION_NOT_FOUND | 找不到匹配的云托管服务版本 |
| AI_MODEL_NOT_FOUND | 未找到指定模型分组 |
423 Locked
功能未启用或路由被禁用。前往控制台开启对应功能，或检查路由配置。
| 错误码 | 说明 |
|---|---|
| HTTPSERVICE_NONACTIVATED | 未开启 HTTP 网关 |
| GATEWAY_ROUTE_DISABLED | 网关路由被禁用，请检查网关路由配置 |
| STATIC_RESOURCE_NONACTIVATED | 未开启静态网站托管服务 |
| AI_MODEL_CONFIG_MISSING | 缺少 API Key 等调用模型的必要配置 |
| AI_MODEL_DISABLED | 模型已停用 |
429 Too Many Requests
请求频率、配额或并发超限。降低请求频率或升级配额后重试。
| 错误码 | 说明 |
|---|---|
| EXCEED_RATELIMIT | 请求频率超过套餐或自定义限频限制 |
| EXCEED_REQUEST_LIMIT | 请求次数超限、套餐资源耗尽 |
| EXCEED_CONCURRENT_REQUEST_LIMIT | 请求并发超限 |
| EXCEED_TOKEN_QUOTA_LIMIT | 大模型 Token 用量已超出配额或分组额度不可用 |
| FUNCTIONS_EXCEED_RESOURCE_LIMIT | 请求频率超过函数预置并发 |
451 Unavailable For Legal Reasons
请求被封禁或合规拦截。检查内容合规性。
| 错误码 | 说明 |
|---|---|
| REQUEST_FORBIDDEN | 请求被禁止访问 |