API errors

Every message the FreeTheAI API answers with, word for word, with what it means and how to fix it. Search this page for the text your app shows (Ctrl+F, or Ctrl+K for the whole site).

Messages that end with an error ID (such as freetheai-1a2b3c4d5e6f) can be looked up by support: keep the ID when you ask for help. Live model status is on the status page.

Error format

Every error has the same JSON body, in the OpenAI style. message is safe to show to people; type and code are for code.

{
  "error": {
    "message": "unauthorized",
    "type": "gateway_error"
  }
}

Some errors carry more fields:

Field	When	Example
error.code	A model ID that does not exist, or a reply blocked by the model's content filter. type is then invalid_request_error.	model_not_found, content_filter
error.error_id	The model failed or a stream broke. The same ID is at the end of the message and in the X-Error-ID response header.	freetheai-1a2b3c4d5e6f

An unknown model, for example, answers 404 with:

{
  "error": {
    "message": "model \"fta/zai/glm-9\" was not found. Use a model ID from https://api.freetheai.org/v1/models, for example fta/zai/glm-5.3 (the full list is on https://freetheai.org/models).",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

A stream that breaks after it started ends with an error event instead of [DONE]:

event: error
data: {"error":{"message":"stream interrupted. Error id: freetheai-1a2b3c4d5e6f","type":"gateway_stream_error","error_id":"freetheai-1a2b3c4d5e6f"}}

Status codes

Status	Meaning	What to do
400	The request is invalid, uses a setting the model does not accept, or was refused by the model's content filter.	Fix the request, reset your app's generation settings, or rephrase.
401	The API key is missing, incomplete, revoked, or expired.	Send Authorization: Bearer ftai_... with a full, active key.
402	Paid requests only (paid models are coming soon).	Use a free model.
403	The request is not allowed: email not confirmed, no check-in today, the key's model or IP list does not include it, the account is on hold, or the request comes from an app or route that is not accepted.	Read the message: each case is listed below.
404	No model has that ID.	Copy an exact ID from freetheai.org/models or GET /v1/models.
413	The body is larger than 8 MB, images included.	Shorten the chat or send fewer or smaller images.
429	A limit was reached: one request at a time, the daily free requests, a usage window, or a rate limit.	Wait for the running reply or the reset. See limits.
502	The model failed this time, or the stream broke.	Retry or pick another model. Keep the error ID if it repeats.
503	The model is busy, paused, or out of free capacity right now.	Retry in a minute or pick another model. These never count against your limits.

Requests turned away because a model is busy, and requests that fail, do not count against your daily free requests.

Your key and account

The request reached FreeTheAI, but the key or account cannot use it yet.

401 Unauthorized

Message: unauthorized

The request has no API key, or the key is wrong, revoked, or expired.

Fix:

1. Send the key as Authorization: Bearer ftai_... (in most apps: paste it into the API key field).
2. Check the key is active at freetheai.org/dashboard/api-keys. If it was revoked or you lost it, create a new one.

401 Not a complete key

Message: This is not a complete FreeTheAI API key. A key starts with ftai_ and is 53 characters long

Only part of a key was pasted, usually the short start the API keys page shows.

Fix: The full key is shown only once, when you create it. If you no longer have it, create a new key and paste the whole key into your app.

403 Daily check-in required

Message: Daily check-in required for free models. Visit https://freetheai.org/checkin to solve the captcha.

Free models need a quick check-in once a day. It resets at 00:00 UTC.

Fix:

1. Sign in on freetheai.org and do the check-in, then send the request again. Your key does not change.
2. Paid models never need a check-in.

403 Email not confirmed

Message: Confirm your email address to use the API.

The account has not confirmed its email address yet.

Fix: Sign in on freetheai.org, send the confirmation link, and open it from your inbox (check spam).

403 Account on hold

Message: This account's API access is on hold pending an abuse review.

API access for this account is paused while it is reviewed.

Fix: Open Support in your dashboard and send an appeal. Holds are reviewed by people; one account per person.

403 Address not on the key’s allowlist

Message: This API key only accepts requests from the IP addresses on its allowlist

The key has an IP allowlist and the request came from another address (home addresses change often).

Fix: Add your current address to the key, or clear its IP allowlist, at freetheai.org/dashboard/api-keys.

403 Model not allowed on this key

Message: This API key's model list does not include this model.

The key is limited to certain models, and this is not one of them.

Fix: Add the model to the key, or clear the key’s model list, at freetheai.org/dashboard/api-keys.

403 Relayed request

Message: Requests relayed through a Cloudflare Worker are not accepted.

The request came through another service instead of from your app or device.

Fix: Call the API directly. In RisuAI on the web, turn on Settings > Advanced Settings > Force Plain Fetch.

403 App not supported

Message: LoreBary is not supported on FreeTheAI. Use your API key directly in another app.

Requests from this app are not accepted.

Fix: Use your key in another app; the setup guides at freetheai.org/setup cover 24 of them.

The request itself

The request was refused before any reply, because of what it asks for.

404 Model not found

Message: was not found. Use a model ID from https://api.freetheai.org/v1/models

No model has that ID. Model IDs look like fta/zai/glm-5.3; old IDs from freetheai.xyz no longer work.

Fix: Copy an ID from freetheai.org/models or from GET https://api.freetheai.org/v1/models, including the fta/.../ part.

400 Model accepts text only

Message: This model accepts text only. Remove the images, or pick a model that accepts images

The request has images, and this model cannot read them.

Fix: Remove the images, or pick a model marked for images on freetheai.org/models.

400 Key set to tool-capable models only

Message: This API key is set to tool-capable models only, and this model cannot take tool calls.

The key has the "Tool-capable models only" switch on, and this model cannot use tools.

Fix: Pick a model from /v1/models (the key only lists tool-capable ones), or turn the switch off on the API keys page.

400 Media model on a chat endpoint

Message: This model generates media. Create a task with POST /v1/videos or POST /v1/images/generations

Image and video models run as tasks, not chat.

Fix: Create a task with the endpoint named in the message and poll it until it completes (see freetheai.org/docs).

400 Content filtered

Message: Content filtered: the model's content filter blocked this request or its reply.

The model’s own safety filter refused the message or its reply. It is not a fault with your key.

Fix: Rephrase the message, or use another model.

400 Content filtered on dog/ or lion/ models

Message: Content filtered: dog/ models are for general questions, writing, and images.

The fta/dog/ and fta/lion/ models are for general questions, writing, images, and research. Their filter often refuses coding, roleplay, and character chats.

Fix: For coding or roleplay, use an fta/zai or fta/kimi model.

400 Settings the model does not accept

Message: the model rejected one of the request's settings

A generation setting (temperature, top_p, penalties, max tokens) has a value this model refuses.

Fix: Reset your app’s generation settings to their defaults and try again.

400 No message from you

Message: the model needs at least one message from you in the request

The request only had system or character messages. Some apps send that by default.

Fix: In SillyTavern: API Connections > Prompt Post-Processing > Semi-strict. In other apps, set role handling to semi-strict or strict.

400 Conversation too long

Message: the conversation is too long for this model

The chat is longer than this model can read at once.

Fix: Lower your app’s context size, or start a new chat.

400 Request rejected as invalid

Message: the provider rejected this request as invalid; check the messages and parameters.

The model refused the request’s shape: an empty message, an unusual role order, or a parameter it does not take.

Fix:

1. Reset your app’s generation settings, and turn on semi-strict prompt processing if your app has it.
2. If it keeps happening, open a ticket with the error id from the message.

400 Invalid JSON

Message: invalid json payload

The request body is not valid JSON for this endpoint.

Fix: Check the body, and that the URL matches the format you send (for example /v1/chat/completions for OpenAI chat).

400 Missing model

Message: missing model

The request does not name a model.

Fix: Set the model field to an ID from freetheai.org/models.

413 Request too large

Message: request body is too large

The request is over the size limit, usually a long chat with many images.

Fix: Shorten the chat history or lower your app’s context size, and send fewer or smaller images.

Your limits

Free accounts have daily limits. These reset on their own; the Free usage page in your dashboard shows how much you have used.

429 Too many requests at once

Message: concurrency limit reached: your account already has as many requests running as its plan allows.

A reply is still running, and free accounts run one request at a time. Coding tools often send several at once.

Fix: Wait for the current reply to finish (or stop it), then send again. Most coding tools retry these on their own.

429 Daily free requests used

Message: You've used today's free requests. They reset at 00:00 UTC

The account has used today’s free requests. Failed requests do not count. Accounts without Discord linked are told that linking it gives more free requests every day.

Fix: Wait for 00:00 UTC, or raise the limit: link your Discord account on the Free usage page, or see the other ways listed there.

429 Free usage window used

Message: You've used your free usage for this 5-hour window.

The account used its free usage for this 5-hour window (there are also daily and weekly windows).

Fix: Wait until the time in the message, or link Discord on the Free usage page for higher limits.

429 Request too large for the free tier

Message: This request is too large for the free tier.

One request is bigger than the free tier allows. Accounts without Discord linked have a smaller per-request size.

Fix:

1. Lower your app’s context size or start a new chat, then retry.
2. Link your Discord account on the Free usage page to send larger requests.

429 Daily budget for these models used

Message: Daily token budget for this provider is used up.

Some model families have a daily token budget per account, and yours is used for today.

Fix: Use another model until 00:00 UTC; every other model still works. The Free usage page shows each budget.

429 Rate limit

Message: rate limit reached

Too many requests in a short time.

Fix: Slow down and retry after a short wait.

Busy or paused models

The request was fine, but the model cannot take it right now. These are not your limits, and other models keep working.

503 Model busy

Message: this model is busy right now; try again in a minute or pick another model.

The model has no free capacity this minute. These refusals do not count against your limits.

Fix: Retry in a minute, or pick another model.

503 Shared daily limit reached

Message: has hit its shared daily limit (for everyone, not your own usage).

Some models share one daily limit across everyone so they last all week. When it is used up, the model is paused for everyone until the time in the message, even if your own allowance still has room. The status page shows which models are paused.

Fix:

1. Use another model until then; for coding, fta/zai/glm-5.3 is a good switch.
2. Check freetheai.org/status for when it is back.

503 Paused while capacity refills

Message: this model is paused for everyone while its shared capacity refills

The model is paused for everyone for a few hours while its capacity refills.

Fix: Use another model meanwhile, and check freetheai.org/status.

503 Free capacity used up

Message: this model's free capacity is used up right now

The model’s free capacity is used for now.

Fix: Try again later, or pick another model.

503 Model temporarily unavailable

Message: this model is temporarily unavailable

The model is offline for now.

Fix: Try again later, or pick another model.

502 Upstream temporarily unavailable

Message: upstream provider temporarily unavailable.

The model did not answer this time. These do not count against your limits.

Fix:

1. Retry. For long replies, turn on streaming in your app: very long replies without streaming can time out.
2. If it keeps happening, open a ticket with the error id from the message.

502 Upstream rate limited

Message: upstream provider is rate limited.

The model is getting too many requests this minute.

Fix: Retry in a minute, or pick another model.

502 Model server error

Message: the model's server hit an error; try again in a moment.

The model’s server failed this time.

Fix: Try again in a moment.

502 Stream interrupted

Message: stream interrupted. Error id:

The reply stopped partway. A cut-off that delivered almost nothing is not counted.

Fix: Regenerate the reply. If it keeps happening, open a ticket with the error id.

503 Free request check unavailable

Message: the free request check is temporarily unavailable; try again in a moment.

A short hiccup on our side while counting the request.

Fix: Try again in a moment.

400 Request failed

Message: request failed

Something went wrong that has no more specific message.

Fix: Check the model ID and the request body. If it keeps happening, open a ticket with the time, the model, and your app’s name.

Paid usage (coming soon)

Paid models and plans are coming soon. These messages only apply to paid requests; the free tier never spends money.

402 Insufficient wallet balance

Message: insufficient wallet balance

The wallet does not have enough balance for this paid request.

Fix: Add credits on the Credits page, or use a free model.

402 Key budget used

Message: api key budget exhausted

The key reached the spending budget set on it.

Fix: Raise or clear the key’s budget at freetheai.org/dashboard/api-keys.

Messages from your app

Common messages your app shows that do not come from the API itself.

App Claude Code: two keys set

Message: Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set

Claude Code found two keys in your environment and may use the wrong one.

Fix: Keep only ANTHROPIC_AUTH_TOKEN set to your FreeTheAI key, and unset ANTHROPIC_API_KEY. The Claude Code guide is at freetheai.org/setup/claude-code.

App Failed to fetch / NetworkError

Message: Failed to fetch

The browser did not send the request at all. The usual cause is a key pasted only partly, or with a stray character.

Fix: Create a new key, paste the whole key, and reload the app. Check the base URL is https://api.freetheai.org/v1.

App No response from bot

Message: No response from bot

The app gave up waiting while the model was still thinking. Long chats on thinking models take longer to start.

Fix: Retry, turn the model’s thinking off on your key (API keys page), or use a faster model.