Provider troubleshooting¶

This page covers issues with the upstream provider (OpenRouter). Public clients can do very little here beyond recognizing the problem. Most actions live in operator docs.

429 from OpenRouter¶

OpenRouter rate limits apply. The gateway retries up to 3 times with exponential backoff before returning 429 to the client.

Symptoms. Sudden spike in sgw_requests_total{status="429"}. The structured logs show "OpenRouter API failed after retries with status 429".

Client action. Back off. Reduce request rate.

Operator action. Check OpenRouter's dashboard for the key. If the limit is persistent and traffic is justified, request a higher quota from OpenRouter.

5xx from OpenRouter¶

Symptoms. Spike in sgw_requests_total{status="500"|"502"|"503"|"504"}. The logs show OpenRouter API failed after retries with status <code> or OpenRouter connection failed: <reason>.

Client action. Re-issue once. If it persists, treat the upstream as unavailable and use a different model or wait.

Operator action. Check OpenRouter's status page. Cross-reference with artifacts/WAVE-H/PROVIDER-EVENTS.jsonl (the canonical provider event log from the post-production validation). If the outage is sustained, consider toggling model aliases via the registry — but that requires a release.

GLM fallback firing too often¶

Symptoms. Non-zero sgw_routing_decisions_total{action="FALLBACK_GLM_INVOKE"}. Look at the upstream error rate for Pro.

Client action. None — the fallback is already happening.

Operator action. Check OpenRouter's status for DeepSeek V4 Pro. If the outage is sustained, the policy has no automatic remediation beyond GLM-5.2; consider an architectural change (new release) to extend the cross-family fallback chain.

GLM fallback also failing¶

Symptoms. sgw_routing_decisions_total{action="FALLBACK_GLM_FAIL"} is non-zero. The gateway returns 500 to the client.

Client action. Treat as a sustained upstream outage. Wait for OpenRouter to recover.

Operator action. Consider whether to deploy a hot-fix that routes Pro requests to Flash temporarily. Do not edit the registry in production — issue a release.

Auth error from OpenRouter¶

Symptoms. 500 from the gateway with OpenRouter API error: 401.

Client action. None — the server-side OpenRouter key is bad.

Operator action. Rotate the OpenRouter key following the procedure at docs-internal/operations/secret-rotation.md (operator-only).

Provider-side content refusal¶

Symptoms. 500 from the gateway with OpenRouter API error: 400 and an OpenRouter-supplied refusal reason.

Client action. Rephrase the prompt. If you suspect the privacy gate has incorrectly upgraded the request to sensitive=true, examine the privacy gate's output (the structured logs do not include the redaction details, but the policy decision records the original and redacted message counts).

Operator action. None.

What the gateway does NOT do¶

It does not pre-screen prompts for content policy. OpenRouter handles that.
It does not maintain a list of "good" model IDs. The registry is frozen; the operator must update it via a release.
It does not retry non-retryable 4xx errors. 400 / 401 / 403 from OpenRouter come back to the client immediately.