Risoluzione dei problemi

Trova il sintomo e prova la soluzione. Se qui niente aiuta, contatta l’assistenza indicando il request_id.

La prima chiamata fallisce

401 «Missing credentials». L’header Authorization non è arrivato. Verifica che la variabile d’ambiente sia impostata nella shell o nel processo che esegue la richiesta (echo ${POPNOW_API_KEY:0:10} deve mostrare sk-popnow-) e che un proxy o una libreria HTTP non stia scartando l’header.

401 «Key format is not recognized». Il valore non è una chiave PopNow: spesso è qualcos’altro rimasto negli appunti. Le chiavi iniziano con sk-popnow-.

401 «Credentials are invalid or expired». La chiave è stata revocata, è scaduta o è scritta male. Creane una nuova nella console API.

40310. L’indirizzo email dell’account non è verificato. Apri il link nell’email di registrazione; subito dopo la chiave funziona.

40201 «Insufficient balance». L’account non ha crediti sufficienti per la trattenuta di questa attività. Le trattenute per i video possono essere alte; controlla il prezzo con jobs/quote e acquista crediti.

La richiesta viene rifiutata

400 che nomina un campo. L’input non corrisponde allo schema del modello: un campo scritto male, un valore fuori dall’elenco consentito o un campo obbligatorio mancante. Apri la pagina di riferimento del modello da Modelli e confronta.

400 «Invalid callback URL». La callBackUrl deve essere HTTPS pubblico sulla porta 443, senza nome utente né password. localhost e gli indirizzi privati vengono rifiutati.

40004. Il modello funziona, ma ora non può gestire questa combinazione di impostazioni. Cambia quella citata in msg (spesso risoluzione, durata o proporzioni).

50301. Il modello al momento non accetta attività. Riprova più tardi o scegli un altro modello.

413. Il corpo JSON supera i 2 MiB, di solito per colpa di immagini incorporate. Caricale invece.

L’attività fallisce

invalid_asset. Un file di riferimento non si è potuto scaricare o leggere. Apri l’URL in una finestra privata del browser: deve scaricare il file stesso, senza accesso. Le pagine di condivisione dei cloud non funzionano.

content_rejected. Il modello ha rifiutato il prompt o un’immagine di riferimento. Riformula, usa riferimenti diversi o prova un altro modello.

timeout o expired. Il lavoro è durato più del consentito. Prova una durata più breve o una risoluzione più bassa.

generation_failed. Il modello è partito ma non ha prodotto nulla. Lo stesso input spesso fallisce di nuovo; cambia prompt o impostazioni.

Le attività fallite e scadute non consumano crediti.

Il risultato

Il link di download restituisce 403 o «expired». I link firmati durano circa 20 minuti. Rileggi l’attività con recordInfo per averne uno nuovo.

Il link di download fallisce quando invio la chiave API. Non inviare Authorization al link firmato: il link stesso è il permesso.

recordInfo restituisce 404 per un’attività che ho creato. Le attività sono visibili solo alla chiave che le ha create. Usa la stessa chiave o cercala nella console API.

Webhook

Non arriva niente. Verifica che l’URL sia raggiungibile da Internet in HTTPS, che il firewall lo consenta e che l’handler risponda 2xx entro 15 secondi. Le consegne fallite sono elencate nella console API.

La firma non corrisponde mai. Calcola l’hash dei byte grezzi del corpo, non di un JSON riserializzato; usa data.taskId, l’header X-Webhook-Timestamp e il segreto generato più di recente.

La stessa attività arriva due volte. Dopo un nuovo tentativo è normale. Ignora i duplicati tramite request_id.

Caricamenti

Il PUT riceve 403 dall’archivio. Un header è diverso da quello del ticket. Invia Content-Type e Content-Length esattamente come indicati e nessun header Authorization.

La conferma restituisce 40003. Il file caricato non corrisponde a quanto dichiarato. Chiedi un nuovo ticket con il contentType e i bytes corretti.

La conferma restituisce 409. Il ticket è scaduto (dopo circa 20 minuti). Chiedilo subito prima del caricamento.