FreeModel returns errors in the OpenAI-compatible envelope.
{
"error": {
"message": "Your balance is insufficient.",
"type": "insufficient_user_quota",
"code": "insufficient_user_quota"
}
}
error.type and error.code to decide how to recover.
| Status | Code or type | Meaning | Fix |
|---|
| 401 | invalid_token | The API key is missing, invalid, or revoked. | Check the Authorization: Bearer sk-... header. Create a new key if needed. |
| 400 or 404 | model_not_found | The requested model is not available to your key. | Call GET /v1/models and use a returned ID. |
| 400 | invalid_request | A video request has a seconds value other than "10". | Set seconds to the string "10". |
| 402 | insufficient_user_quota | Your prepaid balance is empty or insufficient. | Add balance in the Console under Billing. |
| 429 | Rate limit error | Too many requests were sent in a short period. | Back off and retry with exponential delay. |
| 500-599 | Server error | FreeModel or an upstream provider could not complete the request. | Retry transient failures with backoff. |
Video request error
A video request with a seconds value other than the string "10" returns a 400 invalid_request error. Videos are fixed at 10 seconds.
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"
}'
error.type and error.code set to invalid_request. Set seconds to "10" and submit the request again.
Retry safely
Retry only errors that can be temporary, such as 429 and 5xx responses. Do not retry an invalid key, an unavailable model, or an empty balance without changing the request or account state.
Log the HTTP status, request ID when present, and the complete error object. Do not log API keys or sensitive prompt content.
