Troubleshooting
When a call is refused, the answer says why. Start there.
Every refusal from the gateway carries an X-Onehouse-Request-Id header. Quote it if you contact support.
One exception
A missing or expired token is refused before the request reaches the gateway, so that 401 has no request id.
When a call is refused
| Code | What it means | What to do |
|---|---|---|
401 | Your token is missing, expired, or for another gateway — or it was sent in Authorization instead of X-Onehouse-Authorization. | Use oh ai-gateway run, which renews it for you. With a pasted token, sign in again and restart your client. See The token header. |
401 access_revoked | An admin revoked your access. A new token is refused too. | Ask a project admin to restore it. |
401 credential_required | This provider uses your own key, not one the gateway holds. | Send your key in Authorization, with the gateway token still in X-Onehouse-Authorization. |
403 model_not_permitted | Your token is fine, but you hold no grant on that model. | Ask a project admin to grant it. See Permissions. |
mcp_tool_not_permitted | You hold no grant on the tool, or on Connect for its server. Arrives as an MCP error, with the code in error.data.code. | Ask a project admin to grant it. See Tool servers. |
400 model_required | The request names no model. | Add a top-level model, or send the X-Onehouse-Model header. |
400 model_not_determinable | The gateway could not find model in the first 256 KiB of the body. | Send the model name in the X-Onehouse-Model header. |
404 model_not_found | No published model has that name. | Run GET /v1/models to see the names you can call. Check the name, not the provider's model id. |
404 model_disabled | The name exists but serves no traffic. | Pick another from GET /v1/models, or ask a project admin. |
404 from the provider | The model was published, but its provider does not serve it under that id any more. | Ask a project admin to repoint the model. See Routing and failover. |
429 | The provider rate-limited you. If the model has another destination, the gateway already tried it. | Wait as long as Retry-After says. Otherwise back off and retry. |
502 upstream_unavailable | The provider was unreachable, or sent an error too large to relay. | Retry shortly. If it persists, ask a project admin to check the provider. |
503 no_provider_configured | No model provider is connected. | Ask a project admin to connect one and publish a model. See Models & Providers. |
503 credential_unavailable | The gateway could not read the provider's key from its secret store. | Ask a project admin to check the provider's secret. |
503 policy_unavailable | No access decision could be made, so the gateway refused to be safe. | Not a grant problem. Contact Onehouse support. |
503 upstream_unavailable | The gateway is skipping this provider after recent failures, and no other destination was ready. Nothing was sent. | Wait as long as Retry-After says. |
504 upstream_timeout | The provider did not start answering within 60 seconds. It is not retried on another destination. | Retry only if the call is safe to repeat — it may still be running, and billed. |
Other things that go wrong
| What you see | What it means | What to do |
|---|---|---|
| Enable AI Gateway is greyed out | You are not a project or account admin, the identity service is not ready, or, on AWS, the customer stack lacks the AI Gateway credential vault key. | Follow the message on the button. See Before you enable. |
| Every call fails, and the Overview says Not serving | The gateway was turned off, which removed it from your VPC. | Choose Resume serving. The gateway redeploys in about 4 minutes. See Turn the gateway off. |
| The client cannot reach the endpoint at all | You are outside the network. | The endpoint is private. See Connect to your VPC. |
| Calls bill to your own provider account | Your client sends a second key, in Authorization or x-api-key. | Send the token in X-Onehouse-Authorization only. See The token header. |
| An agent stopped working and nothing changed on its side | Its service principal was unbound, or its token deleted. | See Agent access. |
Check what the gateway will accept
curl https://ai-gateway-<id>.dp.onehouse.ai/v1/models \
-H "X-Onehouse-Authorization: Bearer $ONEHOUSE_GATEWAY_TOKEN"
This answers with the model names you can call, and nothing else. If this works, your address and token are right and the problem is further in. An empty list means you hold Invoke on no model yet.
Still stuck
Contact Onehouse support, with the X-Onehouse-Request-Id from the refused call.