Cosa fare quando HiAPI restituisce 402 saldo insufficiente (INSUFFICIENT_QUOTA)? Cause e passaggi per la risoluzione

Talvolta, chiamando l'API di HiAPI, si riceve una risposta HTTP 402 con error_code pari a INSUFFICIENT_QUOTA nel corpo della risposta. Questo indica che il saldo Credits dell'account è esaurito e non ha nulla a che vedere con la validità dell'API Key, la correttezza del formato della richiesta o il superamento dei limiti di frequenza. L'attività viene rifiutata prima della creazione, quindi non viene addebitato nulla. La soluzione è quasi sempre la stessa: ricaricare i Credits dell'account dalla pagina di fatturazione e poi ripetere esattamente la stessa richiesta che aveva fallito.

Cause comuni

1. Il saldo è semplicemente 0. I nuovi account ricevono Credits omaggio alla registrazione; una volta esauriti questi e le successive ricariche, qualsiasi chiamata che crea un'attività restituisce 402 finché il saldo non torna positivo.
2. Chiamate ravvicinate in poco tempo, saldo consumato più rapidamente del previsto. I modelli video di solito fatturano in base ai secondi di output; eseguire più clip video di seguito consuma Credits spesso molto superiori a un numero equivalente di attività immagine, e il saldo può esaurirsi senza che ce ne si accorga.
3. Confondere 401 o 429 con 402. Guarda direttamente il codice di stato HTTP e il campo error_code: 401 (error_code simile a permission_denied, Key non valida o disabilitata) e 429 (error_code: RATE_LIMITED, richieste troppo veloci) sembrano entrambi "chiamata fallita", ma la soluzione è completamente diversa da quella del 402, e nei log è facile mescolarli e cercare nella direzione sbagliata.

Passaggi per la risoluzione

1. Verifica prima il saldo. Apri la pagina di fatturazione della console e controlla il saldo Credits attuale: questo passaggio conferma direttamente se il 402 è davvero dovuto al saldo.
2. Ricarica l'account. Aggiungi Credits sempre dalla pagina di fatturazione; non ci sono passaggi aggiuntivi di "sblocco", e appena il saldo diventa positivo la creazione delle attività riesce immediatamente.
3. Riprova la richiesta esattamente com'era. Non serve modificare codice o parametri. Gli stessi prompt, model e altri campi riusciranno direttamente con saldo sufficiente; se non sai quanto costa all'incirca una singola chiamata di un modello, consulta prima la pagina dei prezzi.
4. Imposta un avviso di saldo per evitare il problema la prossima volta. Nelle impostazioni della console è disponibile la funzione Balance Alerts (Avvisi di saldo), che invia un'email quando il saldo scende sotto la soglia impostata, così puoi ricaricare prima che si esaurisca davvero.

Esempio minimo di verifica

Con questa richiesta minima puoi verificare in modo indipendente che il problema è il saldo dell'account, escludendo interferenze del modello o dell'SDK stesso:

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a simple test image of a red circle on a white background"
  }'

Con saldo vuoto, la risposta è strutturata così:

{
  "code": 402,
  "data": null,
  "error_code": "INSUFFICIENT_QUOTA",
  "message": "insufficient account balance; top up and retry"
}

Dopo la ricarica, riprovando la stessa richiesta si ottiene una normale risposta di creazione attività:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-xxxxxxxx" },
  "message": "success"
}

Nota che il campo code coincide con il codice di stato HTTP, error_code è il valore stabile usato per la logica di branching, e data è sempre null quando la creazione fallisce.

Link interni correlati

• Prezzi di HiAPI
• Gestione fatturazione e saldo
• Creazione di attività asincrone (documentazione API)

FAQ

Perché il saldo si è esaurito all'improvviso, senza alcun avviso prima? Per impostazione predefinita, ci si accorge che il saldo è insufficiente solo quando un'attività fallisce davvero con 402. Nelle impostazioni della console, attiva Balance Alerts (Avvisi di saldo): riceverai un'email quando il saldo scende sotto la soglia impostata e potrai ricaricare in anticipo.

Un 402 può interrompere un'attività già in esecuzione? No. INSUFFICIENT_QUOTA viene restituito in fase di creazione dell'attività: a quel punto l'attività non esiste ancora, quindi non si può certo parlare di interruzione di un'attività in corso; blocca soltanto la creazione di nuove attività.

Le richieste fallite con 402 comportano addebiti? No. Il controllo del saldo avviene prima della creazione effettiva dell'attività; 402 significa che l'attività non è stata creata e che nessun Credito è stato detratto dall'account.

402 e limite di frequenza (429) sono la stessa cosa? No. Il limite di frequenza restituisce 429 con error_code pari a RATE_LIMITED, che indica richieste inviate troppo velocemente; 402 indica saldo Credits insufficiente e non ha nulla a che vedere con la frequenza delle richieste; anche la soluzione è diversa.

Come si può saperlo in anticipo prima che il saldo si esaurisca? Apri la pagina di fatturazione della console: puoi vedere il saldo Credits attuale e lo storico completo dei consumi, e impostare lì anche la soglia degli avvisi di saldo.