Skip to main content

AI Gateway errors

What each AI Gateway error from the Anthropic Messages and OpenAI Responses endpoints means, and how to fix it.

These errors come from the Anthropic Messages (/v1/anthropic) and OpenAI Responses (/v1/openai) endpoints when your MSP has activated the AI Gateway. Most of them only happen on AI Gateway USD billing. The messages use the name "LLM Gateway", which is what error messages call the AI Gateway.

These errors have no separate error code. Identify them by the HTTP status and the message. They use each endpoint's normal error shape, with the same error type values on both:

  • Anthropic Messages: {"type": "error", "error": {"type": "...", "message": "..."}}

  • OpenAI Responses: {"error": {"type": "...", "message": "..."}}

403: access refused

Error type permission_error. Retrying won't help until the cause is fixed.

  • "LLM Gateway is not enabled for your organization. Ask your MSP administrator to enable it, or contact Hatz support." Your MSP has activated the AI Gateway, but your organization hasn't opted in and doesn't keep legacy credits. A tenant admin opts in on the Connect a client page, or an MSP admin opts the tenant in from Settings → AI Gateway. The model list returns the same error.

  • "Your role does not include LLM Gateway access." The user who owns the API key needs the Use LLM Gateway permission. The built-in tenant roles include it; check any custom role.

  • "LLM Gateway access for your organization has been disabled by your provider." Your MSP has disabled your organization's AI Gateway access. Your API keys and budget are kept. Ask your MSP to re-enable it.

  • "LLM gateway billing is not available for this request." Your MSP's AI Gateway is suspended, or its setup isn't complete. Contact Hatz support.

  • "The requested model is not available for LLM gateway billing." Not every Hatz model is available for USD billing. Choose a model from the list at https://ai.hatz.ai/v1/anthropic/v1/models, which shows only the models your key can use for USD billing. The same model IDs work on the OpenAI Responses endpoint.

429: budget reached

Error type rate_limit_error, with no Retry-After header. Retrying won't help until the budget is raised or the next month starts (UTC).

  • "Your tenant's LLM Gateway budget has been reached." Your tenant's monthly AI Gateway budget is used up. A tenant admin can raise it on Connect a client, up to the maximum the MSP allows.

  • "Your organization's LLM Gateway budget has been reached." Your MSP's combined monthly cap for all tenants is used up, so every tenant is refused. In this message, "organization" means your MSP. An MSP admin can raise it in Settings → AI Gateway.

Budgets are checked against an estimate of the most a request can cost, so a request can be refused before the budget shows as fully spent. Lowering the request's output token limit (max_tokens or max_output_tokens) can let it through.

These aren't rate limits. A rate-limit 429 includes a Retry-After header and a code such as key_rate_limited; wait and retry. See LLM Gateways for rate limits.

400: the request can't be billed as sent

Error type invalid_request_error. Change the request, then send it again.

  • "The request uses a feature that is not available for LLM gateway billing." The request asks for something that can't be billed on this model. The usual causes:

    • A web search tool on a model other than Claude. On Claude models, Hatz's built-in web search (the web_search_20250305 tool type) is supported; other web search tool types are not.

    • Prompt caching (cache_control) on a model that doesn't support it for USD billing. Remove it, or choose a Claude model.

  • "The request input exceeds the maximum size available for LLM gateway billing." USD billing has a maximum input size, which can be smaller than the model's full context window. Shorten the input, for example by trimming conversation history or attachments.

  • "The request is too complex to verify its LLM gateway billing features." The request body is too large or deeply nested to check. Simplify it and send it again.

503: temporarily unavailable

Error type api_error.

  • "LLM gateway billing is temporarily unavailable." Hatz couldn't confirm how to bill the request, so it refused the request rather than guess. It can happen for a few seconds right after a budget or opt-in change, and in rare cases for organizations that don't use USD billing. Retry after a short wait; the Anthropic and OpenAI SDKs usually retry this automatically. If it keeps happening, contact Support with the request ID.

  • "The requested model is temporarily unavailable for LLM gateway billing." This model is temporarily unavailable on USD billing. Choose another model, or try again later.

  • "Model discovery is temporarily unavailable." The model list couldn't be loaded. Retry after a short wait.

Contacting Support

Include the HTTP status, the error message, the X-Request-ID response header, the model, the endpoint, and the tool or SDK you used. Never include your API key. See API Troubleshooting and Support Diagnostics.

Related articles

Did this answer your question?