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.

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	champ prompt requis	Add a prompt.
400	contenu_interdit	The content filter refused the prompt.
400	image_requise, inpaint_images_requises	The mode needs image_b64, and mask_b64 for inpaint.
401	cle_requise, cle_invalide	Header missing, or unknown key.
402	credits_insuffisants	Not enough balance for this render (cost is given). Top up on the site.
403	cle_desactivee, cle_revoquee, cle_expiree	Key switched off, revoked or expired: create a new one in the app.
403	licence_revoquee, licence_non_pro	Licence revoked, or an account that is not Pro.
403	portee_manquante	The key lacks the permission asked for, named in portee.
403	lora_inconnu	A character that does not belong to the account.
404	media_indisponible	The file is gone: submit again.
413	image_trop_lourde	Source image or mask past 12 MB decoded.
429	trop_de_rendus_simultanes, cadence_minute, plafond_jour	A cap is reached, see Retry-After.
429	plafond_credits_jour	The key's daily credit cap is reached (plafond, depense, cout).
502	soumission_echouee, statut_echoue	An incident on the render side: retry in a few seconds.
503	licence_inverifiable	The account cannot be checked right now: retry in a minute.

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

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.

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