Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Route model calls

Errors from Mubit

Mubit passes your provider's answers back to your app, its errors included. Mubit also answers a call itself when it can't, or won't, send it on. This page explains how to tell the two apart, what Mubit's errors look like, and what each code means. Troubleshooting has each code's message and the fix.

Whose error is it

What you seeWhose it is
An error with the type middleware_gateway_error, or middleware_errorMubit's.
An error without either, on an answer that has x-middleware-request-idYour provider's, as the provider sent it.
An answer without x-middleware-request-idIt didn't come through Mubit's API. Check the base URL.

A call to your Neon AI Gateway is a call to a provider: Neon's errors come back as Neon sent them.

The error format

Mubit's own errors use your provider's error format, so your SDK reads them the way it reads the provider's. Each has the type middleware_gateway_error, a code, a message and the call's request ID. The format follows the path:

PathFormat
/openai/…, /compat/…, /gemini/v1beta/openai/…, and every other path, such as one that gets 404 unknown_routeOpenAI's
/anthropic/…Anthropic's
/gemini/…, except its OpenAI-compatible endpointGemini's

In OpenAI's format, an error looks like this:

{
  "error": {
    "message": "No API key was provided. Send your Mubit key where the provider's SDK sends its API key.",
    "type": "middleware_gateway_error",
    "param": null,
    "code": "missing_key",
    "request_id": "mreq_…"
  }
}

In Anthropic's format, type and code sit in the error object, and request_id is beside it. In Gemini's format, the HTTP status is the error's code, Mubit's code is the reason of its ErrorInfo detail, and the request ID is in a RequestInfo detail. The API reference shows all three.

One error has another type: a call sent to the console's address gets 503 no_provider_configured, with the type middleware_error.

Every answer from Mubit, errors included, carries the call's ID in x-middleware-request-id: see Headers and request IDs. Quote it when you ask for help.

Which errors to retry

Mubit marks errors a retry won't fix with x-should-retry: false, and the ones worth retrying with retry-after, in seconds. SDKs that read these headers stop or wait. The table says which is which.

The codes

CodeStatusIt meansRetry
missing_key401The call carries no Mubit key.No
invalid_key401The key is wrong, revoked or malformed, or the call carries two different Mubit keys.No
key_expired401The key has expired.No
wrong_region401The key belongs to another base URL. Use the one your console's Connect page shows.No
provider_key_refused, subscription_token_refused, jwt_refused, oauth_token_refused, extra_credential_refused, middleware_key_refused401The call carries something other than your Mubit key, such as a provider key, a sign-in token or a second credential, or carries the Mubit key outside the header your SDK uses for its key.No
key_permission, key_scope403The key can't call a provider: it is read-only, or it isn't tied to one project. Use an Inference key made for the project.No
engine_unavailable503Mubit couldn't check the key just now.Yes, after retry-after
provider_key_missing403The project has no key for the provider the path names, and no Neon key that applies.No
provider_region_unavailable403The project's key names a region, or a Neon URL, that Mubit doesn't send keys to. An admin deletes the key and adds it again.No
key_store_unavailable503Mubit couldn't read the project's provider key just now.Yes, after retry-after
unknown_route404The path is outside the provider prefixes, or is a /compat path or method that isn't served.No
unknown_provider404The service in a /compat path isn't served. The message lists the ones that are.No
admin_path_refused403An organization or admin endpoint of a provider. Call the provider directly.No
invalid_path400The path has a . or .. segment, a ;, a control character, or an escape that decodes again.No
upstream_unreachable502Mubit couldn't connect to the provider. Nothing was sent.Yes
upstream_failed502The connection broke after the request started. The provider may have the request.Only if a second call is safe for your app
upstream_redirect502The provider answered with a redirect. Mubit follows none, so a retry gets the same answer.No
upstream_timeout504The provider didn't start its answer in time: see time limits.Stream, or shorten the call
gateway_overloaded503Mubit is at its limit of open provider connections. Nothing was sent.Yes, after retry-after
gateway_draining503The instance that took the call is shutting down. Nothing was sent.Yes, after retry-after
ℹ️Note

Mubit refuses a call for its key, its path or a missing provider key before it asks your provider, and keeps no record of it.

Your provider's errors

An error from your provider keeps its status, headers and body. Its message says why. The usual causes are in Troubleshooting.

Next