fal API 403: User is locked. Reason: Exhausted balance. — and why a top-up may not clear it

Published 2026-09-23

HTTP 403 Do not retry as-is

The exact error

User is locked. Reason: Exhausted balance. Top up your balance at fal.ai/dashboard/billing.

What it means

fal bills Model APIs from prepaid credit. According to fal’s pricing docs, you buy credits in advance and your usage draws them down. When the balance is used up, the account is locked. Every call then fails with HTTP 403, and the JSON body carries the lock message as its detail string. Users quote the message word for word in fal issues #922, #1112 and #1147.

The lock applies to the whole account, not to one key. The reporters in #922 and #1112 both say that creating a new API key did not clear it. The same message format shows up with other reasons too: Insufficient funds in a 2024 report (#180) and TOP_UP in a September 2026 report (#1163).

Official vs community. The fal documentation we checked doesn’t describe this message or how unlocking works. Everything below about unlocking comes from user reports in fal’s public GitHub issue tracker.

The most common complaint is that the lock stays in place after the balance is positive again:

#922 (March 2026): the user topped up $10 and the dashboard showed $9.15, but the API still returned 403. Later commenters disagree about what fixed it. One says a new API key worked, others say it didn’t, and one was unlocked on their own “a few hours later”.
#1112 (July 2026): the account locked after about nine requests in quick succession, while the dashboard showed $8.54 and the balance had never reached zero.
#1147 (August 2026): after a confirmed top-up, a billing balance endpoint still returned a negative value 19 hours later.
#1163 (September 2026): $110.83 in credit. One generation would succeed, then the next was blocked. Support unlocked the account manually, and it locked again within minutes.

At the time of writing, these issues were open and had no reply from fal staff in the threads.

How to confirm it’s this

You get HTTP 403 with a body like {"detail": "User is locked. Reason: ..."}. The detail is a single string. It is not the detail array that fal uses for model validation errors.
Every model fails the same way. In #914, nano-banana-2, flux-2-pro, gpt-image-1.5 and grok-imagine-image all returned the same lock message.
Read-only calls can still work. In #1147, a queue status GET returned 200 while uploads and generation calls returned 403.
In the JS client, a non-422 JSON error is thrown as an ApiError. error.status is 403, and error.body.detail holds the string. Older Python fal_client versions only showed 403 Forbidden without the body (#180, closed in 2024). The workaround in that thread was to read response.content on the exception you caught.

Fix

Check the balance in the fal dashboard. If the credit really is used up, top it up, as the message says.
If the balance is positive and you are still locked, you are in the situation described in the issues above. Reports disagree. Some accounts unlocked by themselves after hours, one user fixed it with a new key, and several needed a manual unlock from fal. Contact fal support with your account details through a private channel. Don’t put your email address or card digits in a public GitHub issue, as many reporters did.
Upgrading the client helped one commenter in #922, who moved to fal_client 0.13.2. Another user said it made no difference. Treat that as a one-off report, not a fix.
Watch your spend so the balance doesn’t hit zero. fal’s pricing docs point to the billing dashboard and the Platform usage APIs for this.

Retry or not

No, at least not as-is and not in a loop. This error comes from the account’s state, not from the request. The same call will keep returning 403 until the lock clears. Reporters say that took hours or needed someone at fal. The fal JS client’s default retry list (429, 502, 503 and 504) doesn’t include 403.

If you build agents, treat this like a circuit breaker for the whole account. Stop sending fal calls, alert a person, and resume only after one manual test call succeeds. Pattern #1163 shows why: a single success does not mean the next call will work.

When it’s not this

Admin lock. A commenter in #914 reported a lock with the reason Admin lock. It isn’t about balance, and only fal support can explain it.
Key problems. A commenter in #922 also saw an error saying the user was not found for the key. That points to the key, not the balance.
Concurrency limits. fal documents a 429 for exceeding your concurrent request limit, not a 403, and the queue retries it automatically.

Error text last verified against the sources below on 2026-09-23.