API docsErrors

API errors and how to fix them

Every message the FreeTheAI API answers with, word for word. Find yours, see what it means, and fix it. Messages that end with an error id: keep the id, and send it with a ticket if the fix below does not help.

Updated 2026-10-16 · Live model status: freetheai.org/status

Your key and account

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

401Unauthorized

unauthorized

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

  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.

401Not a complete key

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.

  1. 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.

403Daily check-in required

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.

  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.

403Email not confirmed

Confirm your email address to use the API.

The account has not confirmed its email address yet.

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

403Account on hold

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

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

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

403Relayed request

Requests relayed through a Cloudflare Worker are not accepted.

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

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

403App not supported

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

Requests from this app are not accepted.

  1. 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.

404Model not found

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.

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

400Model accepts text only

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.

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

400Key set to tool-capable models only

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.

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

400Media model on a chat endpoint

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.

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

400Content filtered

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.

  1. Rephrase the message, or use another model.

400Content filtered on dog/ or lion/ models

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.

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

400Settings the model does not accept

the model rejected one of the request's settings

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

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

400No message from you

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.

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

400Conversation too long

the conversation is too long for this model

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

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

400Request rejected as invalid

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.

  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.

400Invalid JSON

invalid json payload

The request body is not valid JSON for this endpoint.

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

413Request too large

request body is too large

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

  1. 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 Plan page shows how much you have used.

429Too many requests at once

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.

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

429Daily free requests used

Daily free request limit reached. It resets at 00:00 UTC

The account has used today’s free requests. Failed requests do not count.

  1. Wait for 00:00 UTC, or raise the limit: the Plan page lists the ways, such as linking Discord.

429Free usage window used

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).

  1. Wait until the time in the message, or link Discord on the Plan page for higher limits.

429Request too large for the free tier

This request is too large for the free tier.

One request is bigger than the free tier allows.

  1. Lower your app’s context size or start a new chat, then retry.

429Daily budget for these models used

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.

  1. Use another model until 00:00 UTC; every other model still works. The Plan page shows each budget.

429Rate limit

rate limit reached

Too many requests in a short time.

  1. 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.

503Model busy

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.

  1. Retry in a minute, or pick another model.

503Shared daily limit reached

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.

  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.

503Free capacity used up

this model's free capacity is used up right now

The model’s free capacity is used for now.

  1. Try again later, or pick another model.

502Upstream temporarily unavailable

upstream provider temporarily unavailable.

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

  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.

502Upstream rate limited

upstream provider is rate limited.

The model is getting too many requests this minute.

  1. Retry in a minute, or pick another model.

502Model server error

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

The model’s server failed this time.

  1. Try again in a moment.

502Stream interrupted

stream interrupted. Error id:

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

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

503Free request check unavailable

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

A short hiccup on our side while counting the request.

  1. Try again in a moment.

400Request failed

request failed

Something went wrong that has no more specific message.

  1. 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

Paid models spend wallet balance.

402Insufficient wallet balance

insufficient wallet balance

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

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

Messages from your app

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

AppClaude Code: two keys set

Both ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY set

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

  1. 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.

AppFailed to fetch / NetworkError

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.

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

AppNo response from bot

No response from bot

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

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