A troubleshooting guide

Is Droid down, or is it you?

Factory’s status page has a row for the CLI, but its critical sign-in outage in September was posted on another one. Here are the two rows to read, and what each error Droid shows you means.

Open status.factory.ai

Check in a minute

Look at two rows on Factory's page

status.factory.ai has a “CLI” row, but read “api.factory.ai” too: Factory’s September sign-in outage was posted there, not under CLI. The Models group shows trouble at Anthropic, OpenAI and the other model providers.

Read the error's exact words

A model provider that’s overloaded or unavailable is their side; a usage limit, a failed sign-in, your own model key or “Unable to reach” is yours. The table below sorts each one.

Run droid doctor

droid doctor tests DNS, TLS and HTTPS to Factory’s servers, your sign-in, your proxy and certificates, and whether Droid is up to date. --checks connectivity,auth runs just the two that matter here.

The error says whose side it’s on

Droid retries timeouts and answers cut off mid-stream before it shows you anything. Factory’s docs don’t list its errors, so these are the messages Droid itself prints. They sort into three kinds.

What Droid says	Whose side	What to do
`The upstream AI model provider is currently overloaded.`	Whose side: Factory's	The provider behind your model is full. Retry in a moment, or switch with `/model`.
`… is temporarily unavailable. Try again later or choose another model.`	Whose side: Factory's	That one model is down for now; the message starts with its name. Pick another model, and check the Models group on the status page.
`Standard Usage limit reached.`	Whose side: Yours	One of your rolling 5-hour, 7-day or 30-day windows is used up, and a request needs headroom in all three. Run `/limits` to switch to Droid Core or Extra Usage and carry on, or wait for the window.
`No Extra Usage balance.`	Whose side: Yours	The credits for usage past your plan are spent. Buy more, or on a team ask an organization manager to enable additional usage.
`Authentication failed. Your login session may have expired.`	Whose side: Yours	Sign in again with `/login`. If Factory’s sign-in is having an outage, this is how it looks too, so check api.factory.ai on the status page first.
`Authentication failed. FACTORY_API_KEY is set but appears to be invalid.`	Whose side: Yours	A key in your shell is overriding your login. Unset `FACTORY_API_KEY`, or replace it with a key from Factory’s settings.
`BYOK Error: …`	Whose side: Yours	From a model you added with your own API key: that provider refused it. Check the key, its billing and quota, and the provider and base URL in your custom model settings.
`Unable to reach api.factory.ai.`	Whose side: Yours	Your Mac can’t get to Factory: offline, a VPN, or a network blocking it. Droid names the host that failed. Behind a proxy, set `HTTPS_PROXY`.
`Unable to establish a secure connection to …`	Whose side: Yours	Usually a corporate proxy inspecting TLS. Point `NODE_EXTRA_CA_CERTS` at its certificate.
`FACTORY_API_KEY could not be validated because the Factory API is not accessible.`	Whose side: Could be either	Droid couldn't check your key because Factory didn't answer. Check api.factory.ai on the status page, then your network or proxy.

Status page clear and the error keeps coming? Run /status inside Droid for your sign-in and connection, droid doctor --json for a full report, and /bug to send it to Factory with your logs from ~/.factory/logs.

Or let the menu bar check for you

Hear about an outage before you start debugging

Perch reads status.factory.ai for you once you’ve used Droid on your Mac: often while a session is open, less often between them. It watches the CLI row and api.factory.ai together, so a sign-in outage posted only on the API still reaches you. When either shows an outage, a red banner in the menu bar dropdown says so and links to Factory’s incident. A slowdown or maintenance shows as a small icon, and every open problem is listed in Settings → General → Integrations.

It shows what Factory has posted, so in the first minutes of an outage the error in your terminal can arrive before the incident does. The same pass tells you when your Droid is out of date, with the command to update it. How Perch watches agent health.

Get Perch — $29 Download for macOS

Questions

Droid outages, answered

Is Droid down right now?

Check status.factory.ai, Factory's official status page, and look at both the CLI and api.factory.ai rows, plus the Models group for your model's provider. If they're clear and you still get errors, the cause is usually your usage limits, your sign-in or your network, and the exact error says which.

Why watch api.factory.ai and not only the CLI row?

Because Factory doesn't always post Droid's trouble under CLI. Its critical sign-in outage on 18 September 2026 was attached to api.factory.ai, the web app and the desktop app, and not to the CLI row.

How do Droid's usage limits work?

On Factory's individual plans, Standard Usage runs in three rolling windows, 5 hours, 7 days and 30 days, and a request needs headroom in all three. Run /limits to see each one and to switch to Droid Core or Extra Usage when a window runs out; Settings → Usage shows the same.

What does droid doctor check?

DNS, TCP, TLS and HTTPS to Factory's servers and its sign-in provider, your stored sign-in and token, proxy settings, extra certificates, and whether Droid is up to date. Model and MCP checks are opt-in, because they can spend credits. Add --json for a report to attach to a bug.

Does Droid retry on its own?

For some failures, yes. Recent versions retry a request that times out and an answer cut off mid-stream, and retry temporary capacity errors from custom models for longer. An overloaded provider or a usage limit is handed back to you to retry or switch.

The same guide for Claude Code, Codex, Amp and Devin.