fal.ai 'User is locked' (Admin lock, Exhausted balance): What It Means and What to Do
Your fal.ai key returns 403 'User is locked. Reason: Admin lock' or 'Exhausted balance'. What each reason means, how to get unlocked, and how to keep your app running meanwhile.
If your fal.ai requests suddenly fail with 403 and the body says User is locked, the block is on your account, not on your request. Retrying will not clear it, and in most reports a new API key does not clear it either. What you do next depends on the reason in the message: Exhausted balance is a billing lock that a top-up is supposed to lift, and Admin lock is a lock placed on fal’s side that only fal support can remove.
This guide covers what each reason means, the order of steps that gets an account unlocked fastest, and how to keep a product running while you wait.
Sources checked November 22, 2026: fal’s documentation and the public issue tracker of the fal-ai/fal repository on GitHub.
What the error looks like
The API answers with HTTP 403 and a detail string. These are the three variants that appear in public reports:
{"detail": "User is locked. Reason: Exhausted balance. Top up your balance at fal.ai/dashboard/billing."}
{"detail": "User is locked. Reason: Admin lock. Please contact support@fal.ai."}
{"detail": "User is locked. Reason: TOP_UP."}
| Reason in the message | What it means | Who can clear it |
|---|---|---|
Exhausted balance | Billing lock. fal’s FAQ says: “When your credit balance drops below your account’s lock threshold, your account is locked and API requests will be rejected.” | You, by adding credits. If it stays locked after the top-up, fal support. |
TOP_UP | Not described in fal’s docs. In reports it appears next to the Exhausted balance message on the same account, so treat it as the same billing lock. | Same as above. |
Admin lock | A lock set on fal’s side. The message itself tells you to contact support. fal does not publish the criteria. | fal support only. |
Two details are worth knowing before you start:
- The FAQ speaks of a lock threshold, not of zero. A dashboard that still shows a few dollars does not prove you are above the threshold for your account.
- The same FAQ says enterprise customers on invoice billing “are not subject to automatic locking”. If uninterrupted service matters more than pay-as-you-go flexibility, that is the plan to ask fal about.
A different 403: “Access denied”
Not every 403 from fal is an account lock. If the body says access is denied or that you do not have permission to use an endpoint, and there is no User is locked text, the account is open but this key or this endpoint is not allowed. fal’s authentication docs tie 403s of this kind to the permission preset of the API key. Check which key the failing service uses and what preset it was created with. If nothing changed on your side and a whole endpoint family started refusing a key that worked yesterday, that is a question for fal support, with the endpoint id and the full error body.
You are not the only one
The fal-ai/fal issue tracker has more than 25 issues about locked accounts opened between March and November 2026. They fall into two groups.
Locked with a positive balance. Users report the Exhausted balance lock while the dashboard shows credits, for example #922, #1112, #1163 and #1269. In #1163 the reporter writes that the account locked again minutes after a manual unlock.
Admin lock shortly after a top-up. Several reports describe a new or lightly used account being admin-locked right after its first payment, for example #1183, #1248, #1254 and #1281. Another, #1061, came from a developer whose usage spiked during end-to-end testing before a launch.
To be fair to fal: these are individual reports, not a measure of how often it happens, and in the threads fal staff confirm that the accounts were unlocked by support. The reporter of #1281 was unlocked the day after emailing. Other reporters say they waited several days for a first reply. Staff also state in those threads that GitHub is not monitored for account support.
How to get unlocked, in order
1. Read the reason and stop retrying
Log the full 403 body. A locked account is not a transient failure, so take it out of your retry path. Retrying a locked account only fills your queue and delays the alert that someone needs to act.
import requests
class AccountLocked(Exception):
pass
def check_fal_response(resp: requests.Response) -> None:
if resp.status_code == 403 and "User is locked" in resp.text:
# Not retryable: page a human and switch to the fallback provider.
raise AccountLocked(resp.json().get("detail", resp.text))
resp.raise_for_status()
2. Check billing first
Open the billing dashboard and confirm three things: the credit balance, that no invoice is unpaid, and that the payment method is valid. If the reason is Exhausted balance or TOP_UP, add credits. Then send one test request a few minutes later.
3. Email support from the account address
If the reason is Admin lock, or a billing lock survives a top-up, the only channel fal names is support@fal.ai, and staff ask that you write from the email address of the locked account. Put everything they need in the first message so no round trip is wasted:
- The account email and, if you use one, the team name.
- The exact
detailstring and the time of the first failed request. - The receipt or invoice number of your latest top-up.
- One or two sentences on what your product does and why usage changed, if it did (a launch, a load test, a new feature).
4. Things that do not help
- Rotating the API key. The lock is on the account. Reporters who created a fresh key got the same 403.
- Opening a second account. If the lock is a payment or risk review, a duplicate account under the same card usually makes the review slower, not faster.
- Sending the same email again every day. Reply in the existing thread instead, so the history stays in one ticket.
- Filing a GitHub issue instead of an email. It can add visibility, but staff close these and redirect to email.
If you are a team: one account, not one account per person
A pattern that comes up in community questions is a company giving each employee a personal account and funding all of them with the same card. Many new accounts paid from one card is exactly what payment risk systems are built to notice, on any platform. fal’s documented way to do this is a team: a shared workspace with its own billing, where “API keys belong to the team, not to individual members” and admins invite members by email, or by CSV for larger groups. If your accounts were already locked this way, say so plainly in the support email and ask to consolidate into one team.
Keep your product running while you wait
An account lock is the one failure that retries, backoff and a second API key cannot fix. If paying customers depend on your generation pipeline, the practical protection is a second platform that serves the same model families, already integrated and funded, that you can switch to with a config flag.
A few rules make this cheap to maintain:
- Keep the model choice behind your own interface, so the caller asks for “text to image, 1024 × 1024” and not for a vendor URL.
- Classify account-level errors (locked, suspended, out of credits) separately from request-level errors, and fail over only on the first kind.
- Send a small share of real traffic through the fallback every day. A fallback that has not been called in a month tends to be broken when you need it.
Using WaveSpeedAI as the second platform
WaveSpeedAI is a pay-as-you-go API for image, video, audio and 3D models. The model catalog covers the families most fal projects use, including Seedance, Kling, Wan, Veo, FLUX, Seedream and GPT Image. The points that matter for this problem:
- Credits are checked on each request. A request is accepted when the account has enough credits for it. After you top up, the next request goes through; there is no separate unlock step to wait for.
- A clear message when credits run out. The API returns
Insufficient credits. Please top up your account to continue, so your code can tell a billing problem from a model failure. - Auto top-up. You can let the account recharge itself below a balance you choose, which removes the most common cause of an outage at 3 a.m.
- Payment options. Cards, PayPal, Alipay and WeChat Pay.
- Team members on one account. Invite teammates from the dashboard so everyone works from the same balance instead of separate personal accounts.
- Price shown before you run. Each model page shows the cost of the request you configured.
Like every platform, WaveSpeedAI has terms of use and content rules, so read them before you move production traffic.
What a request looks like
Submit a task, then fetch the result with the returned id. The example uses a fast text-to-image model; every model in the catalog follows the same two calls.
curl --request POST 'https://api.wavespeed.ai/api/v3/wavespeed-ai/z-image/turbo' \
--header "Authorization: Bearer $WAVESPEED_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"prompt": "A lighthouse on a cliff at sunrise, soft fog, 35mm photo"}'
curl --request GET "https://api.wavespeed.ai/api/v3/predictions/$PREDICTION_ID/result" \
--header "Authorization: Bearer $WAVESPEED_API_KEY"
The first call returns data.id. The second returns data.status (created, processing, completed or failed) and, when completed, the file URLs in data.outputs.
Mapping from fal
| On fal | On WaveSpeedAI |
|---|---|
| Submit to the queue endpoint of a model | POST https://api.wavespeed.ai/api/v3/<model path> |
| Poll the request status, then fetch the result | GET https://api.wavespeed.ai/api/v3/predictions/<id>/result |
Authorization: Key ... header | Authorization: Bearer ... header |
| Webhook on completion | Supported; see the documentation |
| Python and JavaScript clients | Python and JavaScript SDKs, plus plain REST |
Input names differ between platforms for some models, so check the parameter list on each model page instead of copying a payload across.
If you would rather test in a browser before writing code, the image generator and video generator run the same models as the API.
FAQ
What does “User is locked. Reason: Admin lock” mean on fal.ai?
It means the account was locked on fal’s side rather than by the automatic balance check. The message asks you to contact support@fal.ai. Adding credits or creating a new key does not lift it; fal support has to.
Why is my fal account locked with “Exhausted balance” when I still have credits?
fal’s FAQ says the lock triggers when the balance drops below an account-specific lock threshold, which is not necessarily zero. Separately, a number of public reports describe the lock remaining after a successful top-up, and in those cases support cleared it manually. Top up, wait a few minutes, test once, then email support.
How long does fal take to unlock an account?
There is no published time. In the public threads some users were unlocked within a day of emailing and others report waiting several days for a first reply. Plan for the longer case.
Why does fal return “Access denied” or “You do not have permission to use this endpoint”?
That is a permission error, not an account lock. Check the permission preset of the API key the request used. If the key and your code did not change, send fal support the endpoint id and the error body.
Can multiple fal accounts on one card get locked?
fal does not publish its risk rules. Many accounts funded by a single card is a common trigger for payment risk checks in general, and fal provides teams for sharing one billing account across people, so use a team instead.
Will a new API key or a new account fix it?
A new key will not, because the lock is on the account. A new account is a poor idea while the first one is under review.
How do I avoid downtime from an account lock on any platform?
Keep a second provider integrated and funded, treat account-level errors as non-retryable, and fail over on them automatically. Turn on auto top-up where the platform offers it so that a low balance never becomes a lock in the first place.
/filters:quality(82)/media/images/1773962750383987480_n3hqzHRZ.webp)