Errori

Quando una chiamata non va a buon fine, la risposta ti dà un numero (code) che indica il tipo di problema e una frase (msg) pensata per una persona. Decidi in base al numero; mostra o registra la frase.

L’involucro

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

• code è un codice applicativo. 200 significa successo; tutto il resto è elencato qui sotto.
• In caso di errore non c’è il campo data, tranne per alcuni errori della libreria di asset che aggiungono data.reason.
• Anche lo stato HTTP è impostato (40201 arriva con HTTP 402). Decidi in base a uno dei due, senza mescolarli: ti consigliamo code, più preciso.
• request_id è anche nell’header X-Request-Id. Indicalo quando contatti l’assistenza.

Se una risposta non è proprio JSON — una pagina HTML o di testo dalla rete intermedia —, gestiscila in base allo stato HTTP e registra l’inizio del corpo.

Lingua dei messaggi di errore

msg e l’errorMessage di un’attività fallita sono in inglese per impostazione predefinita. Invia Accept-Language con en, ja, ko, de, fr, es, pt-BR, ru, it o pl, oppure imposta la lingua degli errori API nella console, per riceverli in quella lingua; le altre tornano all’inglese. Le risposte di errore riportano Content-Language. I codici non cambiano mai con la lingua: un motivo in più per non analizzare mai msg.

Quando un modello indica un motivo preciso per il fallimento (per esempio un’immagine di riferimento illeggibile), errorMessage lo riporta in inglese, senza dettagli interni.

Codici generali

Saldo e tetti

Permessi

Un semplice 403 con una chiave valida significa che l’account al momento non può usare l’API; contatta l’assistenza con il request_id.

Disponibilità dei modelli

Nessuno dei due crea un’attività o trattiene crediti.

Codici di errore delle attività

Un’attività accettata che poi fallisce ha state: "failed" e uno di questi valori in errorCode. L’elenco è chiuso: tratta qualsiasi altro valore come upstream_failed.

Un’attività fallita rilascia la trattenuta e quindi non costa nulla (pochi modelli addebitano i rifiuti per contenuto e lo indicano nella loro pagina). errorMessage spiega il motivo a parole; decidi solo in base a errorCode.

Quando conviene ritentare un 409

Scrivere il nuovo tentativo

Ritenta solo ciò che può riuscire al secondo tentativo, aspetta Retry-After quando c’è e altrimenti aumenta l’attesa in modo esponenziale:

const RETRYABLE = new Set([429, 500, 503, 50301]);

async function call(path, init, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(`https://api.popnow.ai/api/v1${path}`, init);
    if (!res.headers.get('content-type')?.includes('json')) {
      throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
    }
    const body = await res.json();
    if (body.code === 200) return body.data;
    if (!RETRYABLE.has(body.code)) throw new Error(`${body.code} ${body.msg} (${body.request_id})`);
    const wait = Number(res.headers.get('retry-after')) * 1000 || 2 ** i * 1000 + Math.random() * 500;
    await new Promise((r) => setTimeout(r, wait));
  }
  throw new Error('out of retries');
}

import random, time, requests

RETRYABLE = {429, 500, 503, 50301}

def call(method, path, attempts=4, **kwargs):
    for i in range(attempts):
        res = requests.request(method, f"https://api.popnow.ai/api/v1{path}", timeout=60, **kwargs)
        try:
            body = res.json()
        except ValueError:
            raise RuntimeError(f"HTTP {res.status_code}: {res.text[:200]}")
        if body["code"] == 200:
            return body["data"]
        if body["code"] not in RETRYABLE:
            raise RuntimeError(f'{body["code"]} {body["msg"]} ({body.get("request_id")})')
        retry_after = res.headers.get("retry-after")
        time.sleep(float(retry_after) if retry_after else 2**i + random.random() / 2)
    raise RuntimeError("out of retries")

Quando ritenti createTask, invia sempre lo stesso Idempotency-Key, così una richiesta che in realtà era riuscita non viene eseguita né addebitata due volte.

Diagnosi

1. Annota request_id e code.
2. Cerca l’attività nei log della console API, per ID attività o request_id.
3. Ancora bloccato? Contatta l’assistenza con request_id, ora (UTC) e code. Non inviare mai la tua chiave API.