Back to Details

api-gateway-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Gateway Troubleshooting

API Gateway 故障排查

Use this skill to find out why requests to a deployed Google Cloud API Gateway fail and how to fix them. Work only from three sources of evidence:
  1. Public Google Cloud documentation, linked from this skill.
  2. The user's own project, read with the user's own credentials.
  3. Files and output that the user provides, such as an OpenAPI document, an error response, or a pasted log entry.
使用此 skill 查明发往已部署 Google Cloud API Gateway 的请求为何失败，以及如何修复。只能依据以下三类证据：
  1. 此 skill 链接的公开 Google Cloud 文档。
  2. 使用用户自己的凭据读取用户自己的项目。
  3. 用户提供的文件和输出，例如 OpenAPI 文档、错误响应或粘贴的日志条目。

Scope

范围

This skill covers only Google Cloud API Gateway. If the question is about Apigee, Cloud Endpoints, or GKE Gateway API, reply that this skill covers only Google Cloud API Gateway, and don't run its steps or commands.
此 skill 仅涵盖 Google Cloud API Gateway。如果问题涉及 Apigee、Cloud Endpoints 或 GKE Gateway API，请回复说明此 skill 仅涵盖 Google Cloud API Gateway，并且不要运行其中的步骤或命令。

Usage Attribution

使用说明

MUST READ: Before executing any 
gcloud
, REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution.
必须阅读：执行任何 
gcloud
、REST API 或 MCP 命令之前，必须阅读并遵循 Usage Attribution 中的说明。

Ground rules

基本规则

RuleWhy
Stay read-only until the user approves a change. While you diagnose, run only 
list
, 
describe
, 
get-iam-policy
, and 
logging read
commands, plus 
nslookup
and 
curl
GET
requests to a path that's safe to call.		Gateways serve production traffic, and the quota metrics and limits of the most recently created API config apply to every gateway of the API.
Before any change, show the exact command, what it changes, and how to undo it, then wait for an explicit yes. Changes include IAM grants, 
api-configs create
, 
gateways update
, Cloud Run ingress changes, and 
gcloud services enable
.		The user owns the project and the change.
Never fix a 
401
or 
403
by making a backend public (
--allow-unauthenticated
, 
--no-invoker-iam-check
, 
allUsers
) or by granting a basic role such as Editor.		Grant the gateway's service account the invoker role on the one backend instead, which keeps least privilege.
Keep every log read bounded: filter on the gateway, set 
--freshness
or a timestamp window, and set 
--limit
.		Unbounded reads are slow and pull in caller data that the diagnosis doesn't need.
Redact API keys, bearer tokens, and JWTs before you show log entries, commands, or files.Request logs and pasted output can contain credentials.
Base every limit, default, and error meaning on a linked public doc or on output from the user's project. If neither explains the problem, say so and escalate.Guessing about undocumented behavior leads to wrong fixes.
Use the user's existing 
gcloud
login. Never ask for passwords, API key values, or service account key files.		Credentials don't belong in a chat transcript.
For Preview features (streaming, MCP, model routing), check the release notes before answering.Preview behavior changes between releases.
规则原因
在用户批准更改前保持只读。诊断期间，仅运行 
list
、
describe
、
get-iam-policy
和 
logging read
命令，以及对可安全调用的路径执行 
nslookup
和 
curl
GET
请求。		Gateway 承载生产流量，并且最新创建的 API config 所对应的配额指标和限制会应用于该 API 的每个 gateway。
进行任何更改前，先展示准确的命令、该命令会更改什么以及如何撤销，然后等待用户明确同意。更改包括 IAM 授权、
api-configs create
、
gateways update
、Cloud Run ingress 更改以及 
gcloud services enable
。		项目及其更改由用户所有。
绝不要通过将后端公开（
--allow-unauthenticated
、
--no-invoker-iam-check
、
allUsers
）或授予 Editor 等基础角色来修复 
401
或 
403
。		应在单个后端上向 gateway 的 service account 授予 invoker role，从而保持最小权限。
限制每次日志读取的范围：按 gateway 过滤，设置 
--freshness
或时间戳窗口，并设置 
--limit
。		无界读取速度缓慢，还会拉取诊断并不需要的调用方数据。
在展示日志条目、命令或文件之前，务必遮盖 API key、bearer token 和 JWT。请求日志和粘贴的输出可能包含凭据。
每项限制、默认值和错误含义都必须基于链接的公开文档或用户项目的输出。如果两者都无法解释问题，请如实说明并升级处理。猜测未记录的行为会导致错误的修复方案。
使用用户现有的 
gcloud
登录状态。绝不要索要密码、API key 值或 service account key 文件。		凭据不应出现在聊天记录中。
对于 Preview 功能（流式传输、MCP、model routing），回答前先检查 release notes。Preview 行为会随版本发生变化。

Prerequisites

前提条件

  1. Google Cloud CLI. Use a recent 
    gcloud
    (the commands here were checked with version 591.0.0); see Install the gcloud CLI. Don't install or update software without the user's approval. If 
    gcloud
    isn't available or the user says not to run commands, work in evidence mode: give the user the read-only commands to run, and diagnose from the output, response bodies, and log entries they paste.
  2. Authentication. Use the user's existing 
    gcloud auth login
    session; this skill doesn't need application-default credentials.
  3. Project. Ask which project hosts the gateway and pass 
    --project={project_id}
    on every command. Don't run 
    gcloud config set
    , because it changes the user's environment. This skill troubleshoots existing gateways and never creates projects.
  4. Billing. The project needs an active billing account even when usage stays in the free tier; see API Gateway pricing.
  5. APIs. API Gateway requires 
    apigateway.googleapis.com
    , 
    servicemanagement.googleapis.com
    , and 
    servicecontrol.googleapis.com
    . A gateway can keep responding while one of them is missing, and its logs then stay empty, so check with 
    gcloud services list --enabled --project={project_id}
    . Enabling a missing API is a change that needs approval.
  6. IAM roles for diagnosis (read-only): 
    roles/apigateway.viewer
    , 
    roles/logging.viewer
    , 
    roles/serviceusage.serviceUsageViewer
    , and 
    roles/iam.serviceAccountViewer
    (to check the gateway's service account). For Cloud Run backends, add 
    roles/run.viewer
    ; to trace a custom domain through its load balancer, add 
    roles/compute.viewer
    ; to check an API key's project, 
    roles/serviceusage.serviceUsageViewer
    is also needed there.
  7. IAM roles for fixes (only after approval): 
    roles/apigateway.admin
    ; 
    roles/iam.serviceAccountUser
    on the gateway's service account, because creating or updating an API config or a gateway requires 
    iam.serviceAccounts.actAs
    ; 
    roles/run.admin
    to change a Cloud Run service's IAM policy or ingress; 
    roles/serviceusage.serviceUsageAdmin
    to enable an API or a managed service, plus 
    roles/servicemanagement.serviceConsumer
    on the API's managed service to enable it in another project; and 
    roles/iam.serviceAccountAdmin
    to re-enable a disabled service account.
  8. Region. Gateways are regional. Use the region that 
    gateways list
    reports. When a fix needs a new gateway, create it in the original gateway's region, or in 
    us-central1
    if the user has no preference; see API Gateway deployment model and Cloud locations.
  1. Google Cloud CLI。 使用较新的 
    gcloud
    （本文中的命令已使用 591.0.0 版本验证）；请参阅 安装 gcloud CLI。未经用户批准，不要安装或更新软件。如果 
    gcloud
    不可用，或用户表示不运行命令，则以证据模式工作：向用户提供需要运行的只读命令，并根据其粘贴的输出、响应正文和日志条目进行诊断。
  2. 身份验证。 使用用户现有的 
    gcloud auth login
    会话；此 skill 不需要 application-default credentials。
  3. 项目。 询问哪个项目承载 gateway，并在每个命令中传入 
    --project={project_id}
    。不要运行 
    gcloud config set
    ，因为这会更改用户的环境。此 skill 用于排查现有 gateway 的问题，绝不创建项目。
  4. 结算。 即使使用量保持在免费层级内，项目也需要启用有效的结算账号；请参阅 API Gateway 定价。
  5. API。 API Gateway 需要 
    apigateway.googleapis.com
    、
    servicemanagement.googleapis.com
    和 
    servicecontrol.googleapis.com
    。缺少其中某个 API 时，gateway 仍可能继续响应，但其日志会保持为空，因此请使用 
    gcloud services list --enabled --project={project_id}
    检查。启用缺失的 API 属于更改，需要获得批准。
  6. 诊断所需的 IAM 角色（只读）： 
    roles/apigateway.viewer
    、
    roles/logging.viewer
    、
    roles/serviceusage.serviceUsageViewer
    和 
    roles/iam.serviceAccountViewer
    （用于检查 gateway 的 service account）。对于 Cloud Run backend，请添加 
    roles/run.viewer
    ；如需通过 load balancer 追踪自定义域，请添加 
    roles/compute.viewer
    ；如需检查 API key 所属的项目，还需要 
    roles/serviceusage.serviceUsageViewer
    。
  7. 修复所需的 IAM 角色（仅在批准后）： 
    roles/apigateway.admin
    ；在 gateway 的 service account 上授予 
    roles/iam.serviceAccountUser
    ，因为创建或更新 API config 或 gateway 需要 
    iam.serviceAccounts.actAs
    ；授予 
    roles/run.admin
    以更改 Cloud Run service 的 IAM policy 或 ingress；授予 
    roles/serviceusage.serviceUsageAdmin
    以启用 API 或 managed service，另需在 API 的 managed service 上授予 
    roles/servicemanagement.serviceConsumer
    以在其他项目中启用它；以及授予 
    roles/iam.serviceAccountAdmin
    以重新启用已禁用的 service account。
  8. 区域。 Gateway 是区域性的。使用 
    gateways list
    返回的区域。如果修复需要创建新 gateway，请在原 gateway 所在区域创建；如果用户没有偏好，则使用 
    us-central1
    ；请参阅 API Gateway 部署模型和 Cloud 区域。

Workflow

工作流

Copy this checklist into your notes and tick it off as you go:
- [ ] 1. Context collected
- [ ] 2. Gateway identified by defaultHostname
- [ ] 3. Expected or transient states ruled out
- [ ] 4. Gateway log entry read (bounded query)
- [ ] 5. One branch chosen from the classification table
- [ ] 6. Root cause stated with redacted evidence and a doc link
- [ ] 7. Fix proposed, approved, and applied (or handed to the user)
- [ ] 8. Fix verified
- [ ] 9. Escalated, if the evidence points to Google Cloud
将此检查清单复制到笔记中，并随着推进逐项勾选：
- [ ] 1. Context collected
- [ ] 2. Gateway identified by defaultHostname
- [ ] 3. Expected or transient states ruled out
- [ ] 4. Gateway log entry read (bounded query)
- [ ] 5. One branch chosen from the classification table
- [ ] 6. Root cause stated with redacted evidence and a doc link
- [ ] 7. Fix proposed, approved, and applied (or handed to the user)
- [ ] 8. Fix verified
- [ ] 9. Escalated, if the evidence points to Google Cloud

1. Collect context

1. 收集上下文

Extract these from the conversation first, and ask only for what's missing:
NeededWhy
{project_id}
of the gateway		Every command is scoped to it.
Failing URL (host and path) or 
{gateway_id}
and 
{region}
Identifies the gateway.
HTTP method, status code, and response bodySeparates gateway errors from backend errors.
Approximate time of the failure, in UTCBounds the log query.
What changed recently (new API config, IAM, backend deploy, DNS)Recent changes are the first place to look.
Authentication used by the caller (API key, JWT, none)Selects the auth branch.
If the project or the host is unknown, stop and ask before you run any 
gcloud
command. Don't guess project IDs, and don't use the active 
gcloud
project instead.
首先从对话中提取以下信息，只询问缺失项：
所需信息原因
Gateway 所在的 
{project_id}
每个命令都限定到此项目。
失败的 URL（host 和 path），或 
{gateway_id}
与 
{region}
用于识别 gateway。
HTTP method、status code 和 response body用于区分 gateway 错误与 backend 错误。
故障发生的大致时间（UTC）用于限定日志查询范围。
最近进行过哪些更改（新建 API config、IAM、backend 部署、DNS）应优先检查最近的更改。
调用方使用的身份验证方式（API key、JWT、无）用于选择身份验证排查分支。
如果项目或 host 尚不清楚，请停止操作并在运行任何 
gcloud
命令前询问用户。不要猜测项目 ID，也不要使用当前激活的 
gcloud
项目代替。

2. Identify the gateway

2. 识别 Gateway

List the project's gateways:
bash
gcloud api-gateway gateways list --project={project_id} \
  --format="table(name.basename():label=GATEWAY,name.segment(3):label=REGION,defaultHostname,state,apiConfig)"
Match the request host against 
defaultHostname
. Don't decide from the URL suffix: a gateway's hostname can use either of two 
gateway.dev
formats or, for older streaming and model-routing gateways, a 
run.app
format. Don't guess the owning project from numbers in the hostname either; list the gateways in the project the user names. A custom domain points at a load balancer whose serverless NEG targets the gateway. See references/triage-and-logs.md for the hostname formats and how to trace a custom domain.
If no gateway in the project matches, confirm the product before going on (see Scope).
Then read the gateway's details, including its API config and streaming mode:
bash
gcloud api-gateway gateways describe {gateway_id} \
  --location={region} --project={project_id}
列出项目中的 gateway：
bash
gcloud api-gateway gateways list --project={project_id} \
  --format="table(name.basename():label=GATEWAY,name.segment(3):label=REGION,defaultHostname,state,apiConfig)"
将请求 host 与 
defaultHostname
进行匹配。不要仅根据 URL 后缀判断：gateway 的 hostname 可以采用两种 
gateway.dev
格式之一；对于较旧的 streaming 和 model-routing gateway，还可以采用 
run.app
格式。也不要根据 hostname 中的数字推测所属项目；请列出用户指定项目中的 gateway。自定义域指向一个 load balancer，其 serverless NEG 以 gateway 为目标。有关 hostname 格式以及如何追踪自定义域，请参阅 references/triage-and-logs.md。
如果项目中没有匹配的 gateway，请在继续之前确认产品是否正确（请参阅范围）。
然后读取 gateway 的详细信息，包括其 API config 和 streaming mode：
bash
gcloud api-gateway gateways describe {gateway_id} \
  --location={region} --project={project_id}

3. Rule out expected and transient states

3. 排除预期状态和瞬时状态

  • Gateway 
    state
    isn't 
    ACTIVE
    :     
    CREATING
    or 
    UPDATING
    means an operation is still running, so wait and check again. 
    FAILED
    means creation failed; read the error of the failed operation. 
    DELETING
    means the gateway is being removed.
  • API config just created: creating a complex API config can take up to ten minutes, and only one config can be created for an API at a time.
  • First requests after an idle period: API Gateway has cold-start latency.
  • Google Cloud incident: check the Service Health dashboard.
  • Gateway 的 
    state
    不是 
    ACTIVE
    ：     
    CREATING
    或 
    UPDATING
    表示操作仍在运行，因此应等待并再次检查。
    FAILED
    表示创建失败；请读取失败操作的错误。
    DELETING
    表示 gateway 正在被删除。
  • 刚创建 API config： 创建复杂的 API config 最长可能需要十分钟，并且一个 API 同时只能创建一个 config。
  • 空闲一段时间后的首次请求： API Gateway 存在 cold-start latency。
  • Google Cloud 事故： 请检查 Service Health dashboard。

4. Read the gateway log entry

4. 读取 Gateway 日志条目

Use a bounded query that prints only the fields you need. Replace 
{status_code}
with the status the caller saw:
bash
gcloud logging read 'resource.type="apigateway.googleapis.com/Gateway" AND resource.labels.gateway_id="{gateway_id}" AND resource.labels.location="{region}" AND httpRequest.status={status_code}' \
  --project={project_id} --freshness=1h --limit=20 \
  --format="json(timestamp,httpRequest.status,httpRequest.latency,httpRequest.requestUrl,jsonPayload.responseDetails,jsonPayload.apiConfig,jsonPayload.apiMethod)"
If you know the failure time, replace 
--freshness
with a 
timestamp>="{start_utc}" AND timestamp<="{end_utc}"
filter that spans about 30 minutes around it. Read 
httpRequest.status
, 
httpRequest.requestUrl
, 
jsonPayload.responseDetails
, 
jsonPayload.apiConfig
, and 
jsonPayload.apiMethod
. Keep the 
--format
field list, because a full entry can contain the caller's credentials, and redact credentials before you quote any field, including a 
key
query parameter in 
httpRequest.requestUrl
.
To compare API configs, compare only the 
apis/{api_id}/configs/{config_id}
part: the same config can appear as a full resource name (
//apigateway.googleapis.com/projects/...
) and with either the project number or the project ID.
jsonPayload.responseDetails
decides the branch: 
via_upstream
means the backend produced the response; any other value means the gateway produced it. The troubleshooting page explains 
via_upstream
and 
service_control_quota_error
, and the model routing page explains the 
model_router_*
values that model-routing gateways log. Quote any other value as-is, and don't explain how the gateway works internally.
使用有界查询，仅打印所需字段。将 
{status_code}
替换为调用方看到的状态码：
bash
gcloud logging read 'resource.type="apigateway.googleapis.com/Gateway" AND resource.labels.gateway_id="{gateway_id}" AND resource.labels.location="{region}" AND httpRequest.status={status_code}' \
  --project={project_id} --freshness=1h --limit=20 \
  --format="json(timestamp,httpRequest.status,httpRequest.latency,httpRequest.requestUrl,jsonPayload.responseDetails,jsonPayload.apiConfig,jsonPayload.apiMethod)"
如果知道故障时间，请将 
--freshness
替换为覆盖故障时间前后约 30 分钟的 
timestamp>="{start_utc}" AND timestamp<="{end_utc}"
过滤器。读取 
httpRequest.status
、
httpRequest.requestUrl
、
jsonPayload.responseDetails
、
jsonPayload.apiConfig
和 
jsonPayload.apiMethod
。保留 
--format
中的字段列表，因为完整日志条目可能包含调用方凭据；引用任何字段之前都要遮盖凭据，包括 
httpRequest.requestUrl
中名为 
key
的 query parameter。
比较 API config 时，仅比较 
apis/{api_id}/configs/{config_id}
部分：同一个 config 可能显示为完整资源名（
//apigateway.googleapis.com/projects/...
），并使用项目编号或项目 ID。
jsonPayload.responseDetails
决定排查分支：
via_upstream
表示响应由 backend 产生；任何其他值都表示响应由 gateway 产生。故障排查页面介绍了 
via_upstream
和 
service_control_quota_error
，model routing 页面介绍了 model-routing gateway 记录的 
model_router_*
值。其他值应原样引用，不要解释 gateway 的内部工作方式。

5. Classify and follow one branch

5. 分类并选择一个排查分支

Pick the first row that matches, and load only the reference file it names.
What you seeLikely causeReference
401
or 
403
with 
via_upstream
The backend rejected the gateway: invoker role, audience, or deleted service accountauth-errors.md
A 
4xx
produced by the gateway whose body names a credential problem (for example 
UNAUTHENTICATED
)		The API key or JWT was rejected; quote the bodyauth-errors.md
500
with no gateway log entry, after log exclusions and a wrong scope are ruled out		The gateway's service account may be deleted or disabledauth-errors.md
500
with 
service_control_quota_error
Quota metric missing from the newest API configconfig-deployment-errors.md
429
with 
service_control_quota_error
The caller exceeded the API's quotalimits-and-escalation.md
404
, 
502
, 
503
, or 
504
, an oversized request, or a timeout		Routing, backend errors, size limits, or the deadline. The docs don't name the status codes for size or deadline failures, so confirm with 
responseDetails
and the body.		backend-routing-and-timeouts.md
CORS preflight fails or latency is highCORS pass-through or slow backendbackend-routing-and-timeouts.md
api-configs create
fails with an error about the OpenAPI document, such as an unsupported extension or an invalid path, parameter, server, or security requirement		A spec problemHand off to 
api-gateway-openapi-spec-authoring
; if it isn't installed, see OpenAPI pre-flight check
api-configs create
fails with a service account, concurrency, or limit error, or 
gateways create
or 
gateways update
fails		Service account, concurrent creates, limits, or the backend deadlineconfig-deployment-errors.md
400
"The request was malformed" from an old TLS client, TLS scan findings, custom domain, or no log entry at all		TLS enforcement, DNS, load balancer, or wrong hostnetworking-domains-tls.md
Errors on several gateways, or on an unchanged config, with healthy backendsPossible Google Cloud issuelimits-and-escalation.md
If the request also needs log queries or backend inspection commands, use triage-and-logs.md.
选择匹配的第一行，并且只加载该行指定的 reference file。
观察到的现象可能原因Reference
401
或 
403
，且带有 
via_upstream
Backend 拒绝了 gateway：invoker role、audience 或 service account 已被删除auth-errors.md
Gateway 自身生成的 
4xx
，且响应正文指出凭据问题，例如 
UNAUTHENTICATED
API key 或 JWT 已被拒绝；请引用响应正文auth-errors.md
500
且没有 gateway 日志条目，并已排除日志过滤条件和作用域错误		Gateway 的 service account 可能已被删除或禁用auth-errors.md
500
且带有 
service_control_quota_error
最新 API config 中缺少配额指标config-deployment-errors.md
429
且带有 
service_control_quota_error
调用方超出了 API 的配额limits-and-escalation.md
404
、
502
、
503
或 
504
，请求过大或发生超时		路由、backend 错误、大小限制或 deadline。文档没有说明大小或 deadline 失败对应的 status code，因此请结合 
responseDetails
和响应正文进行确认。		backend-routing-and-timeouts.md
CORS preflight 失败或延迟过高CORS 透传或 backend 过慢backend-routing-and-timeouts.md
api-configs create
因 OpenAPI 文档问题而失败，例如不支持的扩展，或无效的 path、parameter、server 或 security requirement		Spec 问题移交给 
api-gateway-openapi-spec-authoring
；如果尚未安装，请参阅 OpenAPI 预检查
api-configs create
因 service account、并发或限制错误而失败，或者 
gateways create
或 
gateways update
失败		Service account、并发创建、限制或 backend deadlineconfig-deployment-errors.md
旧 TLS client 返回 
400
The request was malformed
、TLS 扫描发现问题、自定义域异常，或完全没有日志条目		TLS 强制策略、DNS、load balancer 或 host 错误networking-domains-tls.md
多个 gateway、未更改的 config 或健康的 backend 出现错误可能存在 Google Cloud 问题limits-and-escalation.md
如果请求还需要日志查询或 backend 检查命令，请使用 triage-and-logs.md。

6. State the root cause

6. 说明根因

Give the cause, the evidence (redacted, quoted verbatim from logs or command output), and the public doc section that explains it. If the evidence fits more than one cause, list at most three, say what would tell them apart, and collect that evidence before proposing a fix.
给出原因、证据（已遮盖并逐字引自日志或命令输出）以及解释该问题的公开文档章节。如果证据符合多个原因，最多列出三个，说明如何区分它们，并先收集相关证据，再提出修复方案。

7. Propose the fix

7. 提出修复方案

Show the exact command, the resource it changes, its effect on live traffic, and how to undo it. Wait for approval, then run it, or hand it to the user if they prefer. Keep these rules in mind:
  • To change the OpenAPI document, create a new API config and deploy it with 
    gcloud api-gateway gateways update
    . Before you create the config, check quota metrics with the 
    api-gateway-backend-security-and-rate-limiting
    skill, because the newest API config's quota metrics apply to every gateway of the API.
  • Before you create a new API config, check the OpenAPI document with the linter (see OpenAPI pre-flight check).
展示准确的命令、将变更的资源、对实时流量的影响以及如何撤销。等待用户批准后再执行；如果用户更倾向于自行操作，则将命令交给用户。请遵守以下规则：
  • 如需更改 OpenAPI 文档，请创建新的 API config，并使用 
    gcloud api-gateway gateways update
    进行部署。创建 config 前，请使用 
    api-gateway-backend-security-and-rate-limiting
    skill 检查配额指标，因为最新 API config 的配额指标会应用于该 API 的每个 gateway。
  • 创建新 API config 前，请使用 linter 检查 OpenAPI 文档（请参阅 OpenAPI 预检查）。

8. Verify

8. 验证

Read the logs again for new entries after the change, or repeat the failing request. Repeat a request yourself only if it's safe to repeat, such as a 
GET
; otherwise ask the user to repeat it, because a repeated 
POST
can change data in their backend. After 
gateways update
, wait until the gateway's 
state
is 
ACTIVE
before you test.
更改后再次读取日志中的新条目，或重复失败的请求。只有在重复请求安全时（例如 
GET
）才自行重试；否则请用户重复请求，因为重复执行 
POST
可能会更改 backend 中的数据。执行 
gateways update
后，请等待 gateway 的 
state
变为 
ACTIVE
，然后再进行测试。

9. Escalate when the evidence points to Google Cloud

9. 当证据指向 Google Cloud 时升级处理

Escalate to Cloud Customer Care when the service account is active, the required APIs are enabled, and no log exclusion or wrong scope explains it, but requests get 
500
errors with no gateway log entry; when several gateways fail at once without a config change; when errors are intermittent on an unchanged config while the backend logs stay clean; when control-plane operations keep failing with internal errors; or when Service Health reports an incident. Draft the case text with the evidence bundle in limits-and-escalation.md. The user files the case.
当 service account 处于启用状态、所需 API 已启用，且没有日志排除条件或作用域错误能够解释问题，但请求出现 
500
且没有 gateway 日志条目时；多个 gateway 同时失败且没有 config 更改时；config 未更改时错误间歇性发生且 backend 日志保持干净时；control-plane 操作持续因内部错误而失败时；或者 Service Health 报告事故时，请升级至 Cloud Customer Care。按照 limits-and-escalation.md 中的 evidence bundle 起草 case 文本。由用户提交 case。

OpenAPI pre-flight check

OpenAPI 预检查

Run the linter on every OpenAPI file before creating an API config. Run it; don't read its source. If you don't have the file, give the user the command to run:
bash
python3 scripts/lint_openapi_for_gateway.py {spec_path} [{spec_path} ...]
It reads the files only, makes no network calls, and prints JSON findings that each link to the public doc for the limitation. Exit code 
0
means no errors, 
1
means at least one 
ERROR
finding, and 
2
means a usage, parse, or dependency error. The linter needs Python 3.8 or later. YAML input needs PyYAML; ask the user before you install it with 
pip install "PyYAML>=6.0,<7.0"
. JSON input doesn't. Fix the 
ERROR
findings, and then create the API config. If 
api-configs create
still fails on the OpenAPI document, hand off to 
api-gateway-openapi-spec-authoring
, or use the error message if that skill isn't installed. Show 
WARNING
findings to the user and explain them.
创建 API config 前，对每个 OpenAPI 文件运行 linter。请运行它，不要读取其源代码。如果没有该文件，请向用户提供需要运行的命令：
bash
python3 scripts/lint_openapi_for_gateway.py {spec_path} [{spec_path} ...]
它只读取文件，不会发起网络调用，并输出 JSON findings；每项 finding 都链接到说明相应限制的公开文档。退出码 
0
表示没有错误，
1
表示至少存在一项 
ERROR
finding，
2
表示用法、解析或依赖项错误。Linter 需要 Python 3.8 或更高版本。YAML 输入需要 PyYAML；安装前必须征得用户同意，执行 
pip install "PyYAML>=6.0,<7.0"
。JSON 输入不需要。修复所有 
ERROR
findings，然后创建 API config。如果 
api-configs create
仍因 OpenAPI 文档而失败，请移交给 
api-gateway-openapi-spec-authoring
；如果该 skill 尚未安装，则使用错误消息中的信息。向用户展示 
WARNING
findings 并进行说明。

Output format

输出格式

Report findings in this form:
**Problem:** <one sentence in the user's terms>
**Failed hop:** <gateway or backend, and the evidence for it>
**Evidence:** <redacted log fields or command output, verbatim>
**Root cause:** <one or two sentences> (<public doc link>)
**Fix:** <exact command or spec change; approval needed: yes/no>
**Verify:** <how to confirm the fix>
**Open questions:** <anything you couldn't confirm>
按照以下形式报告发现：
**Problem:** <one sentence in the user's terms>
**Failed hop:** <gateway or backend, and the evidence for it>
**Evidence:** <redacted log fields or command output, verbatim>
**Root cause:** <one or two sentences> (<public doc link>)
**Fix:** <exact command or spec change; approval needed: yes/no>
**Verify:** <how to confirm the fix>
**Open questions:** <anything you couldn't confirm>

Related skills

相关 Skills

NeedSkill
Write or change API key, JWT, backend authentication, or quota configuration
api-gateway-backend-security-and-rate-limiting
Write, migrate, or fix an OpenAPI spec, including OpenAPI errors from 
api-configs create
api-gateway-openapi-spec-authoring
MCP 
/mcp
JSON-RPC errors on an MCP-enabled gateway
api-gateway-mcp-server
Deep IAM analysis, such as deny policies or role discovery
iam-helper-for-troubleshooting
Build a load balancer, Cloud Armor policy, or custom domain front end
google-cloud-global-frontend-configuration
Deploy or reconfigure a Cloud Run backend
cloud-run-basics
需求Skill
编写或更改 API key、JWT、backend 身份验证或配额配置
api-gateway-backend-security-and-rate-limiting
编写、迁移或修复 OpenAPI spec，包括 
api-configs create
中的 OpenAPI 错误
api-gateway-openapi-spec-authoring
MCP-enabled gateway 上的 MCP 
/mcp
JSON-RPC 错误
api-gateway-mcp-server
深度 IAM 分析，例如 deny policy 或 role 发现
iam-helper-for-troubleshooting
构建 load balancer、Cloud Armor policy 或自定义域前端
google-cloud-global-frontend-configuration
部署或重新配置 Cloud Run backend
cloud-run-basics

Reference files

Reference files

  • references/attribution.md: usage attribution rules for every command you run.
  • references/triage-and-logs.md: hostname formats, log queries, log fields, metrics, and backend inspection commands.
  • references/auth-errors.md: 
    401
    and 
    403
    on either hop, API keys, JWTs, and the gateway service account.
  • references/backend-routing-and-timeouts.md: 
    404
    , size limits, backend 
    5xx
    , 
    504
    and deadlines, CORS, and streaming.
  • references/config-deployment-errors.md: API config and gateway create, update, and delete failures other than OpenAPI errors, and quota metric conflicts.
  • references/networking-domains-tls.md: custom domains, load balancers, TLS, and requests that never reach the gateway.
  • references/limits-and-escalation.md: product limits, quota increases, unsupported features, and the Cloud Customer Care evidence bundle.
  • scripts/lint_openapi_for_gateway.py: offline linter for documented OpenAPI limitations.
  • references/attribution.md：每条所运行命令的使用说明规则。
  • references/triage-and-logs.md：hostname 格式、日志查询、日志字段、指标和 backend 检查命令。
  • references/auth-errors.md：任一 hop 上的 
    401
    和 
    403
    、API key、JWT 以及 gateway service account。
  • references/backend-routing-and-timeouts.md：
    404
    、大小限制、backend 
    5xx
    、
    504
    、deadline、CORS 和 streaming。
  • references/config-deployment-errors.md：除 OpenAPI 错误以外的 API config 和 gateway 创建、更新及删除失败，以及配额指标冲突。
  • references/networking-domains-tls.md：自定义域、load balancer、TLS，以及从未到达 gateway 的请求。
  • references/limits-and-escalation.md：产品限制、配额提升、不支持的功能，以及 Cloud Customer Care evidence bundle。
  • scripts/lint_openapi_for_gateway.py：用于检查已记录 OpenAPI 限制的离线 linter。