Pro API: limits, error codes and good practice

Caps

Every key carries three: renders at once (2 by default), submissions per minute (60 by default) and, if you set one, a daily credit cap.

Past a cap the answer is 429 with a Retry-After header in seconds. A refused call costs nothing. The day used for the caps is the UTC day.

Long videos add two caps of their own: 30 shots per sequence and 5 sequences in progress per licence (see Videos).

Characters have one: 50 per Pro licence, those made in the app included, and a character left unused for one year is erased (see Characters). Locations, objects and animals have their own, counted separately: 50 per Pro licence (10 with a personal licence, in the app), erased after the same year unused (see Locations, objects, animals, styles and outfits).

Face swap has two of its own: a passage of 20 s at most per render, and our server prepares two videos at a time. Past that, the answer is 429 server_busy: retry after Retry-After (see Face swap). Through the MCP, a Face swap with a transition takes a whole video of 60 s at most, and the server handles two at a time: past that, the tool asks you to try again in a few minutes.

Our own card is shared with the app's users. When it is busy your renders go to rented GPUs, at the same price and through the same API, with a few tens of seconds more at startup.

Error codes

Code	error	What it means, and what to do
400	prompt_required	Add a prompt.
400	forbidden_content	The content filter refused the prompt.
400	invalid_seed	seed must be a whole number from 0 to 4294967295.
400	image_required, inpaint_images_required	The mode needs image_b64, and mask_b64 for inpaint.
401	key_required, invalid_key	Header missing, or unknown key.
402	insufficient_credits	Not enough balance for this render (cost is given). The answer carries buy_url, the credit purchase page of your licence. A render or a training in progress reserves its price until it ends: engaged says how many credits are held aside that way.
402	confirmation_required, payment_declined	A purchase on your saved card (POST /credits/purchase): your bank asks for your confirmation, or declined the payment. Use buy_url, the ordinary purchase link.
409	agent_not_allowed, no_saved_card, monthly_cap_reached	A purchase on your saved card: your agent is not allowed to buy (automatic top-up of your account page), no card is saved, or the purchase would go past your monthly limit. Use buy_url.
409	topup_in_progress, purchase_in_progress	Another payment on your saved card is in progress: wait for it to end.
400	unknown_pack	A purchase with an unknown pack, or a custom amount out of bounds or not a whole step.
503	payment_unavailable	The payment could not be confirmed: we do not know whether the charge went through. Do not retry right away; a charge that went through is credited.
403	key_disabled, key_revoked, key_expired	Key switched off, revoked or expired: create a new one in the app.
403	license_revoked, license_not_pro	Licence revoked, or an account that is not Pro.
403	missing_scope	The key lacks the permission asked for, named in scope.
403	unknown_lora	A character that does not belong to the account.
404	media_unavailable	The file is gone: submit again.
404	unknown_lora	On DELETE /loras/{name}, no file by that name on the account. Note the code: the same name answers 403 when a render asks for a character that is not yours.
411	size_required	A LoRA upload without Content-Length. The body is raw, so the size has to be announced.
413	file_too_large	A LoRA past 800 MB, or past 90 MB in a single upload. Send it in parts. A bare 413 with no JSON body is a different thing: the request never reached the API, see the upload section.
413	part_too_large	One part is bigger than the max_part_size the session announced.
404	unknown_upload_session	The uploadId does not exist, or the session was abandoned (six hours) or cancelled by a rejected part.
503	upload_refused, part_refused	The storage could not be reached during the upload: retry.
507	storage_full	No room left on the server storage (LoRAs, or sequences in progress). The team is alerted: retry later.
415	invalid_safetensors	The uploaded file is not a safetensors.
415	incompatible_lora	The LoRA is for another architecture, named in architecture. Images take Krea 2 only, videos LTX 2.5 or 2.3. Nothing is stored and no quota is spent.
413	lora_quota	The account's LoRA storage is full (20 files or 10 GB). The answer says what is left; delete a file to make room.
413	image_too_large	Source image or mask past 12 MB decoded.
429	too_many_concurrent_renders, rate_limited, daily_cap	A cap is reached, see Retry-After.
429	daily_credit_cap	The key's daily credit cap is reached (cap, spent, cost).
502	submission_failed, status_failed	An incident on the render side: retry in a few seconds.
503	license_check_failed	The account cannot be checked right now: retry in a minute.
400	invalid_extend_frames	An extension whose extend_frames is not 9, 17, 25, 33, 41 or 49, or an extend_video that does not have exactly that many frames.
400	extension_with_transition	An extension cannot also be a transition, except with consistency enhanced: drop end_image, or ask for enhanced consistency.
400	extension_too_short	The length of an extension counts the new frames only, and must be 9 at least.
404	clip_unavailable	The clip to extend is no longer available: extend it sooner, or send its end in extend_video. As a 502, reading it failed: retry.
404	unknown_clip	The clip to extend belongs to another licence.
404	unknown_sequence	The sequence does not exist, belongs to another licence, or has expired.
400	job_id_required, empty_sequence	POST /sequences/{id}/clips without a job_id, or the export of a sequence that has no shot.
409	not_exported_yet	GET /sequences/{id}/file before the export: call POST /sequences/{id}/export first.
404	unknown_export	Project folder export: unknown render, from another licence or submitted more than 24 h ago; ZIP erased (45 min after its first download, 2 h at most).
409	export_in_progress	One project folder export at a time per licence.
413	export_too_large	Project folder over 2 GB: export the shots one by one.
400	unknown_reference	Project folder export: an entry of exclude_references names no reference of the export (no id, name or @mention).
400	invalid_export_options	Project folder export: an option that is not a boolean, an exclude_references that is not a list of texts, or include_film without include_media.
500	export_failed	The export failed (reason in detail): nothing is charged, try again.
422	resolution_mismatch, unreadable_clip	A render filed by hand (POST /sequences/{id}/clips) at another resolution than the sequence, or unreadable.
409	missing_shot	A shot is not finished yet, or no longer available (job_id names it): wait for it to finish, then export again.
409	sequence_exported	The sequence is already assembled.
409	audio_mismatch	A shot with sound in a silent sequence, or the other way round.
413	extend_video_too_large	The clip end you sent is past 8 MB.
413	too_many_shots	30 shots at most per sequence.
422	unreadable_tail	The clip end, sent or read back, is not a readable video.
422	assembly_failed	The shots have different resolutions, or sound on some of them only.
503	ultra_unavailable	Ultra mode is closed for the moment: retry later, or render without quality.
503	ultra_4k_unavailable	A 4K size asked in Ultra: 4K is no longer offered, video goes up to 1080p (1920 x 1088).
400	ultra_incompatible	A transition (end_image) asked in Ultra.
400	extension_4k	The continuation of an older 4K clip: 4K is no longer offered, a 4K clip cannot be continued (ultra_4k_unavailable with quality: "max"). Extend a clip of 1080p at most.
400	resolution_above_quality	A size above 1080p (1920 x 1088) without quality: "max": 1080p is the ceiling in every mode.
400	invalid_keyframes, invalid_keyframe_time, keyframes_mode	Keyframes out of bounds: more than 4, an invalid image or strength; a moment outside the clip, or two keyframes less than 0.5 s apart; a mode other than Quality (Ultra, Multi-Ref), or an extension without consistency enhanced.
400	invalid_consistency, consistency_mode	consistency other than standard or enhanced; enhanced consistency asked in Ultra or in Multi-Ref.
400	consistency_explicit	A prompt that enhanced consistency does not render yet, beyond 20 s (15 s with an end_image), in an extension or in a sequence (a single shorter shot renders in standard consistency): shorten it, or use standard.
403	consistency_licensed_only	Enhanced consistency is reserved for licences.
503	consistency_unavailable	Enhanced consistency is closed for the moment: retry later, or render in standard.
409	consistency_mismatch	A shot whose consistency differs from the sequence's.
422	encoding_mismatch	A render filed by hand (POST /sequences/{id}/clips) whose consistency differs from the shots already filed.
400	invalid_fps, fps_requires_fixed_duration, extend_fps_mismatch	A frame rate (fps) the mode does not have (detail lists the ones it has); enhanced consistency above 30 fps with automatic duration (set duration_auto to false and give length); an extension at a frame rate other than the previous clip's.
409	sequence_fps_mismatch	A shot whose frame rate (fps) differs from the sequence's.
503	keyframes_unavailable	Keyframes are closed for the moment: render without keyframes.
429	too_many_sequences	5 sequences in progress at most per licence: export one, or wait for one to expire.
400	invalid_name, invalid_kind, invalid_photo_role, outfit_too_long, invalid_role	A character field out of bounds (see Characters).
400	image_too_small	A photo under 1024 px on its long side.
415	unsupported_image_format, unreadable_image	A photo or a location image that is not a readable JPEG, PNG or WebP.
404	unknown_character	The character_id is not on your licence, or was erased (one year unused, or deleted in the app).
409	character_limit	The character cap (max) is reached: delete one.
409	character_busy	Its views are being made: wait until status is no longer pending. On POST /characters: the same creation is being saved, send it again a few seconds later.
409	photo_view, empty_character, single_image_sheet	The view that came from the original photo cannot be redone; or the character has no readable view (if the storage refused the read: 503 storage_unavailable, retry); or a sheet imported as a single image (a whole sheet, kept as is): its views are not redone, and it does not dress a new sheet (send view 4 or 1).
409	app_character	An instruction or an uploaded view on a character or a sheet made in the app: reserved for characters and sheets created through the API.
400	instruction_too_long	An instruction longer than 200 characters.
400	outfit_or_views_required	A sheet added with neither outfit nor views: give an outfit to generate, or views.
400	views_required	A sheet added with generate: false: give at least one view.
409	source_sheet_empty	A sheet added without a full-body view or a bust, to a character with neither to start from: send one of them in views.
404	unknown_sheet	Only a sheet added through the API (sheet_origin api) can be deleted with DELETE /characters/{id}/sheets/{sheet_id}.
404	unknown_subject	The subject_id is not on your licence, or was erased after one year unused.
409	subject_limit	The subject cap (max) is reached: locations, objects, animals, styles and outfits count together; delete one.
409	empty_subject	A subject with no readable image.
400	invalid_type, description_too_long, invalid_images	A subject field out of bounds (see Locations, objects, animals, styles and outfits).
400	invalid_image	A subject image that is not a readable JPEG, PNG or WebP of at least 512 px on the long side (index says which one).
400	description_required, invalid_views, invalid_view, invalid_count, too_many_images, prompt_too_long, invalid_instructions	Generate a subject: no description, prompt or start image; a view key the type does not have (detail lists them); count outside 1 to 6, or more than 6 images, start included; a prompt over 2,000 characters; instructions empty, too long or for several views.
409	subject_busy, subject_not_generated, view_exists, views_exist, start_image_missing, start_image_imported	A series is already running on this subject; a subject made from images (add images through /images); a view already done (redo it); a start to redo while views start from it; a failed start to redo first; an imported start, which cannot be redone.
404 / 503	unknown_view, generation_unavailable	A view never asked for (add it); subject generation is not available on the server for the moment: retry later.
400	multiref_characters_required, multiref_incompatible, multiref_mode, multiref_format, invalid_length	Multi-Ref out of bounds: 1 to 4 characters (12 in Ultra), no extension or transition, the formats and lengths of Multi-Ref Video.
400	duplicate_name, invalid_strength, unknown_mention	Two characters with the same name; strength outside 0 to 2; an @Name in the prompt with no character (mentions lists them).
400	voice_requires_audio, voice_slot	A character voice (voice_b64) without sound ("audio": true); or on a character other than characters[0] and characters[1] (the engine supports 2 voices). index says which one.
400	invalid_voice_choice	voice other than character or original in a Face swap, or characters[].voice other than character or generated in Multi-Ref Video.
413	audio_too_large	A character voice past 4 MB, or past 2 MB in a Face swap. Only the first 5 seconds are used (20 in a Face swap): send a short excerpt.
415	unsupported_audio_format	A character voice that is not a readable audio file (WAV, MP3, OGG, FLAC).
400	multiref_too_many_references, invalid_subject_type	More than 4 characters, objects and animals in all, outside Ultra; a subject in the wrong field (a location in subjects, an object as location, a style outside styles, an outfit outside outfits).
400	invalid_count, invalid_view, invalid_lora_pass, invalid_subject_image, invalid_size	Create an image: count 1 or 2, view 1 to 5 and present in the sheet, lora_pass 0.3 to 0.9, the image of a subject among its images, width and height from 256 to 2048.
400	character_not_ready	Create an image: the chosen view of a character has no image yet.
503	multiref_image_disabled	Creating an image is not open on this server yet.
400	multiref_ultra_only, multiref_too_many_images, unknown_wearer	Styles, outfits or motion outside Multi-Ref in Ultra; more than 30 images in Ultra; a worn_by that names no character.
400	invalid_motion, invalid_motion_mode, unreadable_motion, motion_missing	motion with neither motion_id nor video_b64; a mode other than camera or choreography; an unreadable video, or one outside 4 to 30 s (input_video_out_of_limits); a motion_id never uploaded (no PUT).
404 / 409	unknown_motion, motion_already_used	A motion_id that is unknown, already used or older than 2 hours: upload the video again.
413 / 503	motion_too_large, motion_not_open, motion_mode_unavailable	A motion video over 20 MB (20 MB once brought down to 480p); the motion is not open yet (ultra.motion_per_second is null); a mode that is not open yet.
409	extension_link_expired	An extend_job_id your licence does not know, or an Ultra shot older than 24 hours: upload its original (POST /extensions) and pass extend_upload_id.
400	extension_real_face	The video to extend in Ultra was not rendered by the Ultra mode (a render from another mode, for example) and shows a realistic face: nothing is charged. Extend it in Quality mode, or redo the shot in Ultra.
400	extension_ultra_only, extension_ultra_options, invalid_extension_direction, extension_backward_sequence, extension_tail_quality_only	An Ultra extension out of bounds: extend_upload_id or backward without quality: "max" (or from a clip that is not Ultra); a start image, references, motion or enhanced consistency with it; a direction other than forward or backward; backward in a sequence; extend_video in Ultra.
400	extension_too_large, unreadable_extension, extension_upload_missing	An uploaded video above 1080p; an unreadable MP4, or one outside 4 to 30 s (input_video_out_of_limits); a file never uploaded (no PUT).
400	input_video_out_of_limits	A video sent to the Ultra mode (motion, video to extend) outside its limits, checked before the render, nothing charged: limit says which one (duration: 4 to 30 s; total_duration: 30 s with the reference sounds; count: 10; size: 200 MB; format: MP4 or MOV; fps: 24 to 60; pixels: width × height from 409,600 to 8,295,044; aspect_ratio: 0.4 to 2.5), with value, min and max.
404 / 409	unknown_extension_upload, extension_upload_used	An extend_upload_id that is unknown, older than 2 hours or already used: upload the file again.
413 / 503	extension_too_heavy, extension_not_open, extension_backward_unavailable	A file over 60 MB; the Ultra extension is not open yet (ultra.extend_per_second is null); backward is not open yet.
413	references_too_large	The prepared views go past the render's budget: fewer characters, or a smaller format.
400	video_required, character_required	A Face swap without video_b64, or without character_id.
413	video_too_large	A Face swap video past 20 MB: trim or compress it first, or use the MCP tool tendre_face_swap, which takes up to 95 MB.
415	unreadable_video	The Face swap video is not a readable MP4, MOV, WebM or MKV.
400	invalid_start, invalid_duration, passage_too_short	A Face swap passage out of bounds: start below 0 or past the end of the video; duration outside 0.5 to 20 s; a passage shorter than half a second.
400	invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part	A Face swap field out of bounds: zone other than tight, normal or wide; part other than full or head; likeness outside 0.5 to 2; scene over 400 characters; description over 360; name over 60.
413	face_swap_too_large	The passage is still too heavy once prepared: give a shorter duration.
429	server_busy	Our server is already preparing two Face swap videos: retry after Retry-After (20 s). The MCP upload link answers the same code as a 503 when too many files are waiting: retry in a few minutes.
503	face_swap_unavailable, face_swap_price_missing	Face swap is closed, or has no price, for the moment: retry later.
503	creation_unavailable, multiref_unavailable, storage_unavailable	The service is unavailable for the moment: retry later.
500	internal_error	An unexpected incident on the server side: retry, and tell us if it happens again.

Ultra billed per second (Ultra):

Code	error	What it means, and what to do
400	resolution_outside_ultra	Above 1080p: 480p, 720p or 1080p.
400	engine_refused	The engine refuses the text or an image: the reason is in detail and the code in code. Nothing is charged: rephrase.
502	engine_unavailable	The engine does not answer: retry in a few minutes. Nothing is charged.
409	render_in_progress	Cancel of a render already computing: it no longer stops, it is delivered and billed.
400	invalid_references, references_too_large, multiref_ultra_options, multiref_ultra_explicit	Multi-Ref in Ultra: a reference image is unreadable or too heavy (20 MB at most in all), or an option is not supported.
403	multiref_ultra_unavailable	Multi-Ref in Ultra billed per second is not open to this account yet.

The error names are the exact strings the API returns. Match on them rather than on the message, which may be reworded.

One answer is not an error: a Multi-Ref render or a Face swap with a character that has only one view goes through, with a limited_likeness warning in warnings ({ "code": "limited_likeness", "character_id": "...", "detail": "..." }). The likeness is limited: create the character's seven views for a faithful one.

A Multi-Ref render in Ultra with 9 to 12 characters goes through too, with a many_characters warning: some may be missing or mixed up (8 are recommended).

Good practice

• Poll every 3 seconds, not faster. The queue is shared, and hammering it helps nobody.
• Download as soon as the status is completed. The file is not archived.
• Write prompts in English, and for videos describe the movement rather than the still.
• One key per use, and a daily credit cap on every key that lives on a server. A leaked key with a cap costs you a day, not a balance.
• Treat a 429 as normal, not as a failure: wait for Retry-After and carry on.
• A connection cut before the answer costs nothing. If an image or video submission gets no answer (a proxy timed out, a 524 error, the program stopped), the render is not started, or it is cancelled at once, and nothing is charged: just send the request again. For a batch of images (count), the renders already created are cancelled too. A character's creation goes on: sending the same request again returns the same character, with nothing charged twice (see Characters).

Prompts are logged on our side, as they are for the app, for safety purposes.