Gateway errors and troubleshooting

Gateway failures are easiest to resolve when you identify the stage that rejected the request. This guide groups verified errors by request validation, authentication, model readiness, provider execution, streaming, budget, and platform setup.

The list reflects current handlers and runtime sources; it is not a permanent exhaustive public error registry.

A useful incident record includes the exact error code, HTTP status, request and trace IDs, model status header, provider attempts when present, and the configuration change made before retry. This keeps successive tests comparable. It also exposes when the same visible symptom has moved between layers—for example, from a missing API key to a model-readiness failure after authentication is fixed. Troubleshooting should stop when the evidence reaches an unverified product or environment boundary rather than filling the gap with an assumed control.

Error model

Classify the failure before deciding whether any retry is appropriate.

budget_exceeded is especially important to classify correctly. It is a project control evaluated before provider execution, not a provider billing response. setup_required similarly indicates missing Ethen platform configuration. Both should stop automated retry until the corresponding administrative condition changes.

The model-status response header can clarify readiness failures. Record it with the error code, but do not treat one header value as a permanent model property; runtime status can change with project configuration and provider state.

Gateway errors identify the processing layer that stopped the request. Validation and authentication errors occur before model routing. Setup, catalog, provider-key, model-readiness, and budget errors prevent a valid provider attempt. Adapter and stream failures occur after route selection. internal_error represents an unclassified handler failure.

Use the public error code first, then the request and trace identifiers, model-status header, route metadata, and provider attempts. Do not collapse every non-200 response into a provider outage.

Errors before routing usually reflect malformed input, key state, scope, setup, model readiness, or budget.

Provider-stage failures create attempt evidence and may trigger configured retry or fallback.

Use status, error code, request ID, trace ID, and attempt history together.

The error model uses distinct codes for request validation, key state, scope, setup, model readiness, provider credentials, budget, provider streaming, and internal failure. Preserve the exact code because similar user-visible symptoms can originate at different layers.

Budget enforcement can return budget_exceeded before provider execution. Unclassified handler failures return internal_error. Provider attempts retain redacted diagnostics when available.

Streaming can report provider_stream_error inside the event stream.

Request validation can return invalid_json, missing_model, or missing_messages.

Authentication errors

If setup_required appears while key records cannot be created or verified, inspect the platform dependency before rotating secrets. Repeatedly issuing keys in an unconfigured environment can create confusion without restoring the authentication service.

Provider order, fallback, aliases, and BYOK do not fix these errors because provider execution has not started.

missing_api_key indicates that a usable Bearer credential was not supplied.

invalid_api_key, revoked_api_key, expired_api_key, and insufficient_scope identify separate credential outcomes.

setup_required can indicate missing backing configuration rather than a bad secret.

Authentication errors occur before routing. Add the Bearer header for a missing key, replace an invalid or expired key, stop using a revoked key, and create or select a key with gateway:invoke when scope is insufficient.

Unclassified handler failures return internal_error. Provider attempts retain redacted diagnostics when available. Readiness failures include setup_required, model_catalog_only, provider_key_missing, and model_not_runnable. Check the exact error code and HTTP or run state, then change only the dependency associated with that layer first.

Authentication errors include missing_api_key, invalid_api_key, revoked_api_key, expired_api_key, and insufficient_scope. Authentication, model readiness, policy, budget, routing, provider, streaming, approval, and persistence failures need different remedies.

Model errors

A model can be present in the catalog and still fail project execution checks. Confirm whether the failure is catalog-only, missing provider credentials, unsupported modality, or another non-runnable condition before changing the model ID. That classification determines whether the owner is catalog data, project configuration, provider credentials, or product support.

provider_key_missing should not be grouped with a catalog-only state. The first indicates that routing reached a provider that needs credentials; the second indicates that the model is known but not executable through the current catalog state. Their corrective actions and ownership differ.

missing_model and missing_messages are request-shape errors. model_catalog_only means the catalog record is known but not executable through the current project route. model_not_runnable covers a runtime readiness failure. An unsupported modality or missing provider configuration can contribute to that result.

Check the exact model ID and current runtime status. Do not substitute a provider-specific alias in the client request unless the route contract explicitly calls for it; aliases are normally resolved by routing.

missing_model and missing_messages are request-shape failures.

model_catalog_only means discovery exists without a runnable provider route.

provider_key_missing and model_not_runnable require provider, credential, modality, catalog, or policy investigation.

Model errors require catalog and runtime-status review. A catalog-only model is known but not executable; a non-runnable model lacks a current route; setup-required indicates missing environment configuration rather than a malformed model ID alone.

Diagnose either path from the HTTP status, exact code, and request or trace identifier.

Unclassified handler failures return internal_error; provider attempts retain redacted diagnostics when available.

Provider errors

Redacted provider messages can support diagnosis but should not override the public error code or attempt status. Treat them as supplemental detail because adapter wording can vary.

Circuit-breaker and availability filtering may remove candidates before an adapter call. In that case, the absence of an attempt row is expected. A provider error should be claimed only when the runtime actually attempted that provider or returned a provider-specific readiness code.

When fallback succeeds, decide whether the application may proceed in degraded mode. The response can be valid while still indicating fallbackUsed, a different selected provider, and warnings. Product behavior should make that distinction visible where provider choice affects compliance, cost, latency, or quality.

provider_key_missing means the selected provider lacks the required outbound credential. Provider adapter failures and timeouts create attempt records and can participate in configured retry or fallback. If every eligible attempt fails, the runtime returns the last relevant error.

Inspect the attempt number, provider, model alias, latency, success state, and redacted message. A fallback success does not erase earlier failures. If no attempt exists, investigate eligibility, policy, credentials, or circuit state before blaming the adapter.

Provider timeouts and adapter failures are recorded as attempts and can affect circuit state.

Configured retry or fallback may move execution to another attempt, but no global count is guaranteed.

Inspect redacted provider errors and selected aliases without exposing credentials.

Provider errors should be read with attempt records, provider eligibility, credentials, alias, timeout, and circuit state. More retries are not a repair for a persistent missing credential or policy restriction.

Inspect the exact error code, request or trace ID, and model status header, not from a route name, a visible card, or a type definition by itself.

A provider error with an attempt record means routing reached an adapter. Compare the attempt’s provider, mapped model, latency, and redacted error with the fallback metadata. If another attempt succeeded, investigate degraded resilience rather than reporting the whole Gateway request as unavailable.

Streaming errors

A stream can start successfully and later emit provider_stream_error. The handler sends an error chunk and a terminal [DONE]. Treat the request as failed even if the client displayed partial text. Record the last normal event, error event, headers, request ID, trace ID, and whether a final usage chunk arrived.

The supplied contract does not include resume semantics. Retrying may create a second provider operation and duplicate visible output, so check the original request record before resubmitting.

provider_stream_error can appear inside the SSE sequence before [DONE].

An error event means the generated output is incomplete even if the connection terminates normally.

Preserve partial text separately from a confirmed successful completion.

Streaming errors can arrive inside an already-open SSE response. Capture the error event and identifiers, discard the partial output as incomplete unless the application has an explicit policy for it, and do not treat [DONE] as proof of success.

Debugging checklist

When support investigation is necessary, provide the returned error code, HTTP status, request ID, and trace ID together with the time and affected environment. Add the requested model and any explicit Gateway routing options, but do not include raw API keys or BYOK credentials. This is the batch’s single general escalation checklist; other pages keep their troubleshooting guidance local to the feature.

Separate environment configuration from request configuration. A setup-required platform state should be corrected before evaluating model, provider, or streaming changes.

If the same error repeats across new request IDs, compare the unchanged configuration before increasing retries. Repetition with no provider attempt usually indicates that the request is still failing at validation, authentication, readiness, budget, or policy rather than encountering a transient provider issue.

Avoid broad resets during diagnosis. Replacing keys, changing the model, widening provider lists, and enabling streaming in one step destroys the ability to identify the original cause. Make one grounded change, issue a fresh request, and compare the new request and trace records with the previous result.

1. Record the HTTP status, public error code, request ID, trace ID, and X-Ethen-Model-Status value.
2. Confirm the endpoint, Bearer header, JSON body, model, and nonempty messages.
3. Verify key state and gateway:invoke before changing provider settings.
4. Check model runtime status, project budget, provider credentials, policy, and allow-lists.
5. If attempts exist, read them in order and note retries, fallback, timeouts, and redacted failures.
6. For streams, keep the event sequence and final success or error state.

When support must investigate, provide those identifiers and redacted operational fields. Never include a raw Gateway key, BYOK credential, or unnecessary prompt content.

Validate method, path, JSON, model, messages, Authorization header, key scope, key state, and project setup.

Check catalog runtime status, provider eligibility, BYOK availability, budget, policy, attempts, and circuit effects.

Escalate with request and trace identifiers plus the error code, not with raw keys or provider secrets.

A useful debugging order is: parse the error code, identify the processing stage, correlate request and trace IDs, inspect attempts when present, review model and provider state, and retry only after the relevant condition has changed.

Unclassified handler failures return internal_error. Provider attempts retain redacted diagnostics when available.

The list documents errors visible in the supplied handler and runtime; it is not a guarantee that every deployment exposes identical wording or every internal error detail.

Diagnose the earliest failing boundary first. Authentication codes require a key or scope correction; request-shape errors require a valid model and message list; readiness codes point to catalog state or missing configuration; budget errors belong to project usage controls. Only after those checks pass should provider attempts, timeouts, circuit state, retries, fallback, and streaming behavior become the focus.

Use request and trace identifiers when the handler created them. The attempt list shows whether an adapter was called, and the returned error code identifies the family of failure. Avoid blind retries for revoked keys, denied policy, unsupported models, missing credentials, or exhausted budgets because those conditions require configuration or authorization changes. One support handoff is sufficient: include the identifiers, exact error code, route, requested model, observed provider attempts, and whether the request was streaming, while excluding raw Gateway or provider credentials.