Troubleshooting

Start from what you see. Every error from Mubit names a code: find it under Mubit's errors.

Common problems

The call gets a 401, such as missing_key or invalid_key

Mubit refused the call's key. The error's code says why:

• missing_key: the call carries no key. If your code reads MUBIT_API_KEY, set it in the shell that runs the code.
• invalid_key: copy the key again, or create a new one. Check the base URL against your console's Connect page.
• A code that ends in _refused: the call carries something other than your Mubit key, such as a provider key or a sign-in token, or your Mubit key in the wrong place. With the Anthropic SDKs, check ANTHROPIC_AUTH_TOKEN: unset it, or set it to your Mubit key. With Claude Code, unset ANTHROPIC_API_KEY instead (see Coding tools).
• No middleware_gateway_error in the error: your provider refused the provider key saved for this project. An admin checks it under Provider keys.

Sign-ins to Claude Pro or Max, ChatGPT or Codex can't be used. Use a Mubit key. See Key errors.

The call gets a 403, such as provider_key_missing

If the error's type is middleware_gateway_error, Mubit refused the call. Its code says why:

• provider_key_missing: this project has no key for that provider. A provider the starter credit doesn't cover always needs your own key; the console names the providers it covers. An admin adds it under Provider keys, as Add a key shows.
• key_permission: the key is read-only. Use an Inference key.
• key_scope: the key isn't tied to one project. Use a key created in the project the calls are for.
• starter_credit_route: the starter credit doesn't serve that path. Add your own key for the provider.
• admin_path_refused: the path is an organization or admin endpoint. Call your provider directly for those.

Without middleware_gateway_error, your provider refused it: see Your provider's errors. See also Provider key errors and Key errors.

My call isn't in Requests

• The call didn't go through Mubit. Check that your client uses Mubit's base URL. An answer from Mubit carries the header x-middleware-request-id.
• The call asked Mubit not to keep it. A call sent with x-middleware-store: false, or with x-middleware-record: metadata or off, doesn't show in Requests.
• Mubit refused it before calling your provider. A call refused for its key, its path or a missing provider key leaves no record, so it isn't in Requests. Read the error your app got. See Why a call isn't listed.

A call from a browser fails

Mubit's API answers no CORS preflight request, so a browser refuses to send the call. Call Mubit from your server. That also keeps your key off your users' devices.

A long call or stream stops

Mubit has time limits: 610 s for the provider to start its answer, 15 minutes with no part of the answer going to your app, and 60 minutes in all.

• 504 upstream_timeout: the provider didn't start its answer within 610 s. For long answers, stream: a stream starts as soon as the provider starts writing. Your SDK's own timeout (600 s by default for OpenAI and Anthropic) usually ends the wait first: raise it, or stream.
• A stream that breaks off: it went 15 minutes without sending anything, or ran for 60 minutes. Make sure your app keeps reading the stream.

The call gets a 502, 503 or 504

• 503 with the type middleware_gateway_error: wait the seconds in retry-after, then try again. Nothing was sent to your provider. A 503 with the type middleware_error is no_provider_configured. Any other 503 is your provider's.
• 502 upstream_unreachable: Mubit couldn't connect to your provider. Nothing was sent. Try again shortly.
• 502 upstream_failed: the connection broke after the request started. Your provider may have the request, so Mubit doesn't send it again. Try again if a second call is safe for your app.
• 504 upstream_timeout: see A long call or stream stops.

Calls on the starter credit are refused

The starter credit serves a set list of models, paths and options. Each refusal names what it doesn't serve: change the call as the message says, or add your own key for the provider under Provider keys. See Starter credit errors.

My SDK retries a call Mubit refused

Mubit sends x-should-retry: false on errors a retry won't fix, and retry-after on 429 and 503. SDKs that read these headers stop or wait. Your SDK owns retries: Mubit itself retries only a call it couldn't send at all. See Retries.

A task doesn't train, or an adapter isn't in Try models

Open the task in Tasks, or the adapter in Adapters, and read its status. Create your first adapter explains each one and what to do:

• What each test result means: Passed, Below target, Malformed tool calls, Prompt only and Not tested.
• Why a task is waiting or cannot train: the daily training limit, the pause between trainings, and too few or too long examples.
• Why an adapter is unavailable in Try models: the console's messages, such as Not in Try models: prompt only, and what each one means.

Mubit's errors

Mubit's own errors use your provider's error format. Their type is middleware_gateway_error, and they name a code and the call's request ID. The one exception is no_provider_configured, under Path errors: its type is middleware_error. The API reference shows the format for each provider.

In the messages, {provider} is the provider's name, such as OpenAI or Anthropic. {upstream} is the provider's name, or this workspace's gateway. An ellipsis (…) marks text left out here.

Key errors

Provider key errors

Starter credit errors

These come only on calls the starter credit pays for.

Path errors

Connection and capacity errors

Your provider's errors

Mubit passes your provider's answers back to your app, its errors included.

An error whose type is middleware_gateway_error or middleware_error came from Mubit. An error without either, on an answer that carries x-middleware-request-id, came from your provider as it sent it. An answer without that header didn't come through Mubit's API: check the base URL and try again.

Your provider's message says why. The usual causes:

Find a call's request ID

Each answer carries the call's ID in the x-middleware-request-id header. Mubit's own errors also carry it in their body. It starts with mreq_.

Requests shows how to read the header in Python, TypeScript and curl.

Requests shows its own ID for each call, under Details. It is not the request ID: see Find a call's request ID.

Get help

When you ask for help with a call, include:

• the call's request ID, from x-middleware-request-id;
• when you sent it, with your time zone;
• the status, the error's code and its message;
• the base URL and path, and the SDK you use, with its version.

Never send your Mubit key or a provider key.