Errori

Il Reigniter API utilizza codici standard HTTP stato. Ogni risposta all’errore è JSON.

Corpo di errore

La maggior parte degli errori appare così:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 37
}

Campo	Sempre presente	Cosa c’è
error	Sì	Un messaggio che puoi mostrare a una persona. Potrebbe cambiare la formulazione, quindi non corrispondere a esso.
code	Maggior numero di errori	Un codice maiuscolo stabile. Ricomincia su questo.
details	Alcuni errori	Contesto aggiuntivo, ad esempio retryAfter o dati di utilizzo.
retryAfter	Alcuni 429	Pochi secondi per aspettare prima di riprovare.

Alcuni errori non hanno code, come 404 Job not found e 403 Forbidden. Branch sullo stato per quelli.

Errori di validazione

Quando il corpo della richiesta non corrisponde allo schema, si ottiene 400 con una stringa detail che elenca ogni problema come field: message:

{
  "error": "Validation failed",
  "detail": "aspect: Invalid option: expected one of \"9:16\"|\"16:9\"|\"1:1\"|\"4:5\"|\"4:3\"|\"3:4\""
}

Codici di stato

Stato	Significato	Cosa fare
200	Successo.
201	Creato (webhook).
202	Accettato. Il rendering è iniziato.	Fai un sondaggio sul lavoro o aspetta il webhook.
400	La richiesta fu rifiutata. Non fu addebitato nulla.	Correggi la richiesta. Non riprovare senza cambiarle.
401	Chiave mancante, invalida o revocata API.	Controlla la chiave.
402	Pianificazione, problema di credito o utilizzo.	Leggi code.
403	Conto sospeso, o un lavoro che non è tuo.	Contatta l’assistenza o controlla l’ID del lavoro.
404	Non trovato.	Controlla l’ID o il percorso.
409	Richiesta duplicata o limite raggiunto.	Leggi code.
413	Questo rendering costerebbe più del limite per rendering.	Usa meno scene o un quality più basso.
422	Il render non ha marchio, prodotto o presentatore che lo sostenga.	Vedi Video di realizzazione.
429	Troppe richieste o troppi render contemporaneamente.	Aspetta e riprova. Vedi limiti.
500	Qualcosa è andato storto dalla nostra parte.	Riprova dopo.
502	La pianificazione del tuo brief è fallita. I crediti di pianificazione sono stati rimborsati.	Riprova, o riformula il brief.
503	La restituzione viene sospesa o un servizio è fuori servizio. Non è stato addebitato nulla.	Riprova dopo.

Un percorso sconosciuto sotto /v1/ ritorna 404 con code: "NOT_FOUND".

Codici di errore

Autenticazione e piano

Codice	Stato	Significato
NO_API_KEY	401	Nessun Authorization header, oppure il token non inizia con emp_.
INVALID_API_KEY	401	La chiave è sconosciuta o revocata.
PLAN_UPGRADE_REQUIRED	402	API accesso ha bisogno del piano Agency.
ACCOUNT_SUSPENDED	403	L’account è sospeso.

Crediti e utilizzo

Codice	Stato	Significato
NO_CREDITS	402	L’account non ha più crediti.
INSUFFICIENT_CREDITS	402	Non ci sono abbastanza crediti per questo render.
ABUSE_CAP_EXCEEDED	402	Il limite mensile di utilizzo del piano viene raggiunto.
STORAGE_FULL	402	La libreria video dell’account è piena. Rimuovi alcuni video.
UPGRADE_REQUIRED	402	Il video ha bisogno di un piano a pagamento.
REQUEST_COST_TOO_HIGH	413	Questo render costerebbe più del limite per render.

Vedi Account e fatturazione per crediti e piani.

Richieste di rendering

Codice	Stato	Significato
CONTENT_BLOCKED	400	Il brief o una scena viola le regole del contenuto.
PRODUCT_IMAGE_REQUIRED	400	Questo formato necessita di product_image_url, o product_enabled: false.
PRESENTER_REQUIRED	400	Una scena di dialogo non ha volto. Aggiungi avatar_preset_id, o invia presenter_enabled: false.
UNSUPPORTED_MODEL	400	Una scena ha chiesto un modello di render Reigniter non può usare.
BRAND_REQUIRED	422	È stato chiesto un marchio ma non è stato trovato. Invia brand_logo_url.
NO_ANCHOR	422	Nessuna foto di marchio, foto di prodotto o presentatore. Aggiungine una, oppure non partecipa.
CANVAS_NOT_FOUND	404	Un progetto citato non è in questo caso.
DUPLICATE_REQUEST	409	Questo Idempotency-Key era già usato. Non è stato caricato nulla di nuovo.
PLAN_FAILED	502	La pianificazione del brief fallì. I crediti di pianificazione furono rimborsati.

Con un brief, un Idempotency-Key ripetuto può anche tornare come 402 con il messaggio This request was already submitted. Trattalo come un duplicato, non come un problema di credito.

Tasso e sovrapposizione

Codice	Stato	Significato
RATE_LIMITED	429	Troppe richieste. Aspetta retryAfter (o details.retryAfter) secondi.
CONCURRENT_LIMIT	429	Troppi render che girano contemporaneamente. Aspetta che uno finisca.

Servizio

Codice	Stato	Significato
USAGE_CHECK_UNAVAILABLE	503	L’utilizzo non poteva essere controllato, quindi il rendering fu sospeso. Non veniva addebitato nulla.
DB_UNAVAILABLE	503	Un servizio è brevemente indisponibile.
FEATURE_NOT_AVAILABLE	503	Al momento non è disponibile il rendering.
GLOBAL_KILL_SWITCH	503	Il rendering è messo in pausa per tutti.
FEATURE_KILL_SWITCH	503	Questa funzione è in pausa.
USER_KILL_SWITCH	503	Questo account è temporaneamente limitato. Contatta l’assistenza.

Webhook

Codice	Stato	Significato
UNKNOWN_EVENT	400	Non è un evento a cui puoi iscriverti. La risposta elenca quelli validi.
URL_NOT_DELIVERABLE	400	L’URL non è un indirizzo http pubblico.
HOOK_LIMIT	409	L’account ha già il maggior numero di webhook.

Ritentare in sicurezza

• Riprova 429, 500, 502 e 503 con backoff. Non riprovare altri 4xx invariati.
• Invia sempre un Idempotency-Key su POST /v1/render.
• Nessuna risposta (timeout o connessione interruta): riprova con la stessa chiave. Se la prima richiesta avvia un rendering, il ritentativo viene rifiutato invece di avviarne un secondo.
• Risposta a errore: nessun render è stato avviato per quella richiesta. Correggi la causa, poi riprova con una nuova chiave, perché una richiesta fallita a metà potrebbe aver già usato la sua chiave. I crediti di rendering vengono rimborsati. L’unico addebito che non viene rimborsato è la pianificazione breve, quando il rendering previsto viene poi rifiutato ( vedi Creazione di video).
• Se un render è stato accettato (202) e poi fallisce, il status del lavoro diventa failed e error spiega il motivo. I crediti per lavori che non sono stati fatti vengono rimborsati.