Errors

FreeModel returns errors in the OpenAI-compatible envelope. error.code is the stable machine-readable value; error.type groups it.

{
  "error": {
    "message": "Wallet balance is insufficient",
    "type": "invalid_request_error",
    "param": null,
    "code": "insufficient_funds"
  }
}

Anthropic Messages (/v1/messages) and Gemini native (/v1beta/...) requests return the same HTTP status and message in their protocol’s own error shape (error.type for Anthropic, error.status for Gemini), without error.code.

Quick reference

Status	`error.code`	Meaning	Fix
400	`invalid_json`, `invalid_request`, `unsupported_seconds`, `unsupported_resolution`, `unsupported_aspect_ratio`, `unsupported_size`, `image_input_required`, `invalid_image_urls`, `too_many_image_urls`	A field is missing or not supported by the selected model.	Use the values on the model page. Do not retry unchanged.
401	`invalid_api_key`, `api_key_disabled`, `api_key_revoked`, `api_key_expired`	The key is missing, wrong, or no longer active.	Send `Authorization: Bearer <key>` with an active key.
402	`insufficient_funds`, `api_key_spend_limit_exceeded`	Balance or the key’s spend limit cannot cover the request.	Add balance or raise the key limit.
403	`api_key_model_not_allowed`	The key’s model allowlist excludes this model.	Edit the key or use an allowed model.
404	`model_not_available`	The model is unknown, disabled, or has no live route.	Call `GET /v1/models` and use a returned ID.
409	`idempotency_conflict`	An `Idempotency-Key` was reused with a different body.	Use a new key for a new request.
413	`request_too_large`	The request body exceeds the size limit.	Send media as public URLs instead of inline data.
429	`rate_limit_exceeded`, `api_key_concurrency_exceeded`	Too many requests, or too many in flight on one key.	Wait for `Retry-After`, then back off.
4xx or 502	`provider_http_error`, `provider_task_failed`	The upstream model provider rejected or failed the job; a provider 4xx keeps its status.	Adjust the prompt or media for a 4xx; retry a 502 later.
503	`no_eligible_route`, `provider_route_unavailable`	No healthy route can serve the model right now.	Retry with backoff or pick another model.

400 Bad Request

Meaning: The body or parameters do not match the selected model’s contract. Common causes:

A seconds, resolution, aspect_ratio, or size value the model does not list
seconds sent to a model whose length follows a source clip
Missing required media, such as image_urls for an image-to-video model
Private, local, or non-HTTP media URLs
Malformed JSON or a missing model, messages, or prompt

How to fix: open the model page under API Manual, match its allowed values, and resubmit. Do not blind-retry the same payload.

curl https://api.freemodel.app/v1/videos \
  -H "Authorization: Bearer $FREEMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-t2v",
    "prompt": "A paper airplane glides through a sunlit library",
    "seconds": "5"
  }'

Gemini Omni T2V only accepts "10", so this returns 400 with error.code unsupported_seconds.

401 Unauthorized

Meaning: Authentication failed. How to fix:

Create or rotate a key under Console > API Keys.
Send Authorization: Bearer <key> on every request, without quotes or extra whitespace.
Keep the key on the server only.

402 Payment Required

Meaning: The gateway reserves the maximum possible charge before calling the provider. insufficient_funds means your balance cannot cover that reservation; api_key_spend_limit_exceeded means the key’s own spend limit would be exceeded. How to fix: add balance under Console > Billing, or raise the key’s spend limit. For text models, a smaller max_tokens (or max_completion_tokens) lowers the reservation.

404 Not Found

Meaning: model_not_available — the model ID is unknown, disabled, or has no live route. How to fix: call GET /v1/models with the same key and copy an ID exactly. Also confirm the protocol: a model is only served on the protocols listed on its page (for example, Gemini models answer generateContent, GPT-5 models do not).

429 Too Many Requests

Meaning: rate_limit_exceeded (request rate) or api_key_concurrency_exceeded (requests in flight on one key). How to fix: wait for the Retry-After header, then retry with exponential backoff and jitter. Cap parallel video submissions.

502 and 503

Meaning: 502 means the upstream provider failed the request or task (provider_http_error, provider_task_failed). 503 means no healthy route could take it (no_eligible_route, provider_route_unavailable). How to fix: retry with exponential backoff. For async tasks, check task status before resubmitting so you do not pay for a duplicate. Contact support with the status, time, model ID, and the x-gateway-execution-id or task ID — never the API key.

Retry safely

Status	Retry?	Notes
400, 401, 403, 404, 409, 413	No	Fix the request, key, or model first
402	No	Add balance or raise the key limit
429	Yes	Honor `Retry-After`, then back off
502, 503	Yes	Exponential backoff; cap attempts

Log the HTTP status, x-gateway-execution-id, and the complete error object. Do not log API keys or sensitive prompt content.

Rate limits — throttle behaviour and backoff
Task status — poll async jobs
Service status — where to check availability

Getting Started

Development Guide

Quick reference

400 Bad Request

401 Unauthorized

402 Payment Required

404 Not Found

429 Too Many Requests

502 and 503

Retry safely

​Quick reference

​400 Bad Request

​401 Unauthorized

​402 Payment Required

​404 Not Found

​429 Too Many Requests

​502 and 503

​Retry safely

​Related

Quick reference

400 Bad Request

401 Unauthorized

402 Payment Required

404 Not Found

429 Too Many Requests

502 and 503

Retry safely

Related