Reference
Errors
Every error code and what to do.
Error format
Error
{
"success": false,
"message": "Your API balance is $0.20 and this costs $0.50. Add funds at https://open.qulture.io/console.",
"error": "insufficient_balance",
"retry_after": 30 // only on 429
}Branch on error, not on message (messages may change and may be translated). Field validation failures return 422 with an errors array: [{ "key": "mode", "error": "mode field is oneof", "condition": "oneof" }].
Billing errors
402 insufficient_balance: your API balance is lower than the price — the message includes both; nothing was made or charged. Top up in the Console or turn on auto-recharge. 429 concurrency_limit: too many generations running at once; retry when one finishes. 403 developer_account_suspended: paid calls are paused for this account, for example after a top-up payment was refunded or disputed; add funds in the Console to settle what's owed.All codes
| Status | error | What to do |
|---|---|---|
| 400 | studio_invalid_input | A field is missing or wrong (for example no prompt for text_to_video). Read message. |
| 400 | studio_template_not_found | Use an id from GET /studio/templates. |
| 400 | developer_webhook_invalid | webhook_url must be a public https:// URL. |
| 400 | developer_invalid_amount | Top-up amount is outside the allowed range (see min_topup_usd / max_topup_usd in GET /developer/pricing). |
| 401 | developer_key_invalid | Check the key: whole string, starts with qk_live_, sent as Authorization: Bearer … |
| 401 | developer_key_revoked | The key was revoked. Create a new one in the Console. |
| 402 | insufficient_balance | Your API balance is lower than the price (the message shows both). Nothing was made or charged. Add funds in the Console: https://open.qulture.io/console |
| 402 | studio_insufficient_credits | Connector (MCP) keys only: not enough Studio plan credits. Top up or upgrade on Plans. |
| 403 | developer_account_suspended | Paid API calls are paused for this account, for example after a top-up payment was refunded or disputed. Add funds in the Console to settle any amount owed; otherwise contact support@joinqulture.com. |
| 403 | developer_scope_denied | API keys can't call this endpoint (billing and top-ups, posting to Qulture, avatars, key management). Do it in the Console or in Studio while signed in. |
| 403 | studio_disabled | Studio is paused for maintenance or for this account. Try later or contact support. |
| 403 | studio_tier_requires_plan | Connector (MCP) keys only: Standard and Pro need a paid Studio plan. API keys can use every tier. |
| 403 | studio_duration_requires_plan | Connector (MCP) keys only: 10-second videos need a paid Studio plan. |
| 403 | studio_hd_requires_plan | Connector (MCP) keys only: HD needs a paid Studio plan. |
| 403 | studio_limit_reached | Connector (MCP) keys only: a Studio plan limit was reached (for example daily jobs). Try tomorrow or upgrade. |
| 403 | studio_character_limit | The character limit is reached. Delete a character first. |
| 404 | studio_not_found | No such job / image, or it belongs to another account. |
| 409 | studio_job_not_ready | The job is still in progress. Wait for ready. |
| 409 | developer_payment_method_required | Auto-recharge needs a saved card. Make one top-up first (Console). |
| 413 | studio_file_too_large | Images ≤ 10 MB, video ≤ 50 MB. |
| 415 | studio_unsupported_image | Use JPEG, PNG, WebP or HEIC. |
| 415 | studio_unsupported_media | Audio: mp3, m4a, wav, aac. Video: mp4, mov. |
| 422 | studio_consent_required | The photo shows a person: send consent: true after getting their permission. |
| 422 | studio_blocked | A content check refused the request; see block_category. Refused by our check before processing: not charged. Refused by the video or image model after processing (images): charged. |
| 422 | studio_media_too_long | Audio and video inputs must be 15 seconds or less. |
| 422 | studio_identity_mismatch | The selfie doesn't match the character photos. |
| 429 | rate_limited | Over 60 requests/minute, or over the hourly generation limit for this key (200 for API keys, 20 for connector keys). Wait Retry-After seconds. |
| 429 | concurrency_limit | Too many generations running at once for this account (20 by default). Wait for one to finish, then retry. |
| 429 | studio_rate_limited | Too many jobs for this account right now. Wait retry_after seconds. |
| 500 | studio_internal | Something broke on our side. Retry; if it persists, contact support with the job id. |
| 503 | studio_busy | Video engines are at capacity. Nothing was charged; retry in a minute. |