Skip to content
Nexus

Troubleshooting

Determine the failing Nexus layer, provider-call boundary, request identifier, and safe retry action.

Updated View as Markdown
Audience: operatorPlane: operationsAuth: noneStatus: beta

Outcome

从 Gateway 的稳定错误 Envelope 判断故障层、Provider 是否被调用、能否重试，以及后端应查询哪个 Request ID。

Start with the response

{
  "error": {
    "message": "Quota is insufficient for this request",
    "type": "rate_limit_error",
    "param": null,
    "code": "quota_exceeded",
    "request_id": "req_01J...",
    "reset_at": "2026-08-21T00:00:00.000Z"
  }
}

优先保存响应 Header x-nexus-request-id；错误 JSON 的 error.request_id 应与它一致。x-nexus-quota-remaining 和 x-nexus-quota-reset 只在相关响应存在。不要用 Trace ID、Provider Request ID 或 Admin API Request ID 替代 Gateway Request ID。

Gateway error matrix

HTTP / code Layer Provider called? Retry? First check
400 invalid_gateway_route Request routing No No, fix request 必须匹配 /providers/{UUID}/{path...}
400 unsafe_provider_path SSRF guard No No, fix request 后缀是否包含绝对 URL/不安全引用
400 invalid_usage_request Usage Inspector input No No, fix payload 可计量端点要求的请求结构
401 invalid_inference_key Authentication No No, rotate/fix Key 类型、撤销和过期
403 workspace_access_denied Access No No, fix lifecycle Access 状态/起止时间、当前 Period
404 provider_connection_not_found Workspace isolation No No, fix ID/status UUID 是否属于同一 Workspace 且 ACTIVE
409 metering_unsupported Usage Inspector No No, change endpoint 端点无 Inspector，未开启不计量透传
429 quota_exceeded Quota admission No At reset/change availableUnits 与 reset_at
502 provider_configuration_error Saved connection No No, repair config Base URL、密文和 Keyring 配置
502 provider_unavailable Provider transport Attempted Bounded backoff Provider Attempt 和上游状态
503 access_unavailable PostgreSQL/Access service No Backoff DB/Access Readiness、连接池
504 provider_first_byte_timeout Provider transport Yes Risk-aware Provider Attempt，是否可能已执行
504 provider_overall_timeout Provider stream Yes Risk-aware 已输出内容、Reservation 终态

上游 Provider 自己返回的状态和 Body 可以被代理；此时 Provider 已调用。保留 Nexus Request ID 和 Provider Attempt ID，再按上游错误语义处理。

Request reached no provider

对 Authentication、Access、Quota、Inspector、Connection Resolution 或 SSRF Guard 的拒绝，不应存在 Provider Attempt。检查：

  1. ApiKeyBinding → WorkspaceAccess → Workspace 是否解析成功。
  2. Access 是否 ACTIVE 且未越过 accessEndsAt。
  3. 当前 QuotaPeriod 的 availableUnits 是否覆盖 Reservation。
  4. UUID 是否为同一 Workspace 中 ACTIVE 的 ProviderConnection。
  5. 路径是否有 Usage Inspector。

Request reached the provider

查询 Workspace Invocations，再用 Invocation ID 读取详情。对 Timeout、断开和取消，确认 Reservation 最终进入 SETTLED、RELEASED 或 EXPIRED，重复完成事件不能重复扣量。不要因为客户端没收到响应就假定 Provider 没执行。

Service and deployment failures

Symptom Checks
Admin Ready, Gateway not Ready DATABASE_URL、Auth/Secret Driver、Gateway Port、依赖构建
Gateway Ready, requests return access_unavailable PostgreSQL/Access Service 可用性、连接池、迁移版本
reservedUnits 持续增长 Worker Readiness、Outbox/Queue Lag、Reservation recovery
Console works but SDK URL fails Console dev proxy 与生产 Gateway Origin 是否混淆
Cloudflare deploy guard fails 全零 KV/Hyperdrive ID、.invalid Origin、缺少绑定资源
Provider verify fails 上游权限、Base URL、Redirect、认证和 Timeout；不要输出 Secret

Escalation packet

提供以下已脱敏信息：UTC 时间范围、Adapter/版本/Artifact Digest、错误码与状态、Nexus Request ID、Workspace/Access/Connection/Invocation ID、Quota Snapshot 和相关 Health/SLO。不要提供任何 Key、Authorization Header、Provider Secret、数据库 URL 或未批准的请求正文。

Next steps

Navigation

Type to search…

↑↓ navigate↵ selectEsc close