> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.aiplanet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Symptoms, likely causes, and what to check.

| Symptom                                                           | Likely cause                                                                                | Check                                                                                                                           |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| 401 `missing_api_key`                                             | Missing/malformed bearer header                                                             | `Authorization: Bearer ...`                                                                                                     |
| 401 `admin_authentication_required` / `invalid_admin_credentials` | Missing/expired console session or incorrect login                                          | Sign in again on the private operator origin; verify the deployment-owned username/password secret                              |
| 429 `admin_login_rate_limited`                                    | Global or per-username rolling login bucket is full                                         | Wait for `Retry-After`; investigate repeated failures before raising the limit                                                  |
| 503 `admin_login_throttle_unavailable`                            | Redis-backed login enforcement is unavailable                                               | Restore Redis and readiness before allowing password login                                                                      |
| 429 `oidc_login_rate_limited`                                     | The global OIDC initiation bucket is full                                                   | Wait for `Retry-After`; investigate initiation traffic before raising the limit                                                 |
| 503 `oidc_login_throttle_unavailable`                             | Redis-backed OIDC initiation enforcement is unavailable                                     | Restore Redis and readiness before allowing SSO initiation                                                                      |
| 401 `oidc_login_failed`                                           | State expired/replayed, token validation failed, or subject is not mapped                   | Start a new SSO login; verify exact issuer/subject mapping and IdP client registration                                          |
| 503 `oidc_provider_unavailable`                                   | Discovery, token, or key endpoint is unavailable/unsafe                                     | Verify IdP availability, HTTPS endpoints, issuer equality, and client secret                                                    |
| 503 `admin_audit_unavailable`                                     | The pre-action audit event could not be persisted                                           | Restore Postgres/audit readiness; the mutation did not run                                                                      |
| `X-Gateway-Audit-Status: failed`                                  | The outcome event failed after processing                                                   | Correlate `X-Request-ID`, inspect target state, and do not retry blindly                                                        |
| 401 `invalid_api_key`                                             | Wrong or rotated token                                                                      | Key secret and `/admin/keys` status                                                                                             |
| Previous token stopped working                                    | Rotation overlap expired or another rotation replaced the prior generation                  | Install the newest one-time token; inspect `previous_token_valid_until` metadata                                                |
| 403 `endpoint_not_allowed`                                        | Key lacks exact route scope                                                                 | `allowed_endpoints` including `/v1` form                                                                                        |
| 403 model denial                                                  | Alias not granted                                                                           | `/v1/gateway/info` and key `allowed_models`                                                                                     |
| 400 `unsupported_param`                                           | Endpoint/model rejects a field                                                              | Remove field or choose compatible alias                                                                                         |
| 400 output-limit error                                            | TPM/budget needs maximum output                                                             | Add `max_completion_tokens` or `max_output_tokens`                                                                              |
| 429 rate limit                                                    | RPM/TPM exhausted                                                                           | `Retry-After`, key limits, traffic fan-out                                                                                      |
| 429 budget exceeded                                               | Available budget cannot cover reservation                                                   | `/admin/budgets`, output cap, period reset                                                                                      |
| 503 limit backend unavailable                                     | Redis cannot be reached                                                                     | `/ready`, Redis network/TLS/credentials                                                                                         |
| `shared_cooldown_unavailable` log event                           | Redis cooldown read/write failed; direct-HTTP routing is using process-local cooldown state | Restore Redis and readiness; verify healthy providers/fallbacks continue serving                                                |
| `model_catalog_ready: false` with `serving_ready: true`           | Replica is lagging or cannot activate the latest graph, but retains a safe runtime          | `model_catalog_activation_failed`, `/admin/model-catalog` propagation status, database health, repair or reset pending revision |
| `data_retention_ready: false`                                     | Lease, purge, or retention-state persistence failed                                         | `/admin/data-governance`, `data_retention_failed`, Postgres health                                                              |
| 502/504 provider error                                            | Upstream authentication/network/timeout                                                     | Provider status, secret, API base, timeout                                                                                      |
| `/health` works but traffic fails                                 | Liveness is not readiness                                                                   | Private `/ready` component flags                                                                                                |
| Usage missing                                                     | Log queue exhausted during DB outage                                                        | `gateway_request_logs_dropped_total`                                                                                            |
| Cost missing                                                      | Provider usage/cost unavailable or route unpriced                                           | `costed_requests`, model pricing snapshot                                                                                       |
| Config reload changes one instance                                | Reload is process-local                                                                     | Deploy immutable config to every process                                                                                        |

## Collect for support

* Response `X-Request-ID` and timestamp.
* Gateway version/image digest and instance header.
* Endpoint, alias, streaming flag, status, and error code.
* Redacted `/ready` result and relevant metric/log events.
* Do not send bearer tokens, provider keys, database URLs, prompt content, or webhook values.