Errori

L’API usa i codici di stato HTTP convenzionali: 2xx indica un esito positivo, 4xx che la richiesta deve essere modificata e 5xx un problema da parte nostra o di un servizio a monte. Tutte le risposte di errore hanno lo stesso formato JSON, così puoi gestirle in un unico punto.

Formato degli errori#

{
  "error": {
    "code": "invalid_request",
    "message": "\"resolution\" must be one of: 480p, 720p",
    "param": "resolution"
  }
}

• code — una stringa stabile e leggibile dalle macchine. Usala per le condizioni nel codice, non il messaggio.
• message — una spiegazione leggibile dalle persone e sicura da registrare nei log. La formulazione può cambiare.
• param — presente quando l’errore è causato da un campo specifico della richiesta.

Codici di errore#

Errori durante una generazione#

Un errore HTTP indica che la richiesta è stata rifiutata e non è stato addebitato nulla. È diverso da una generazione accettata che non riesce in seguito: la chiamata API è riuscita (anche se POST /run restituisce 202 quando un job fallisce subito) e lo status della generazione diventa failed con un oggetto error. L’importo bloccato viene rimborsato automaticamente. Lo stesso oggetto compare in GET /generations, nel payload di webhook e nei risultati degli strumenti MCP.

{
  "status": "failed",
  "error": {
    "code": "generation_failed",
    "message": "ByteDance's safety review for Seedance 2.0 Fast rejected this request (the prompt or an input file).",
    "reason": "content_blocked",
    "hint": "Describe the character's look instead of naming a copyrighted character or real person, keep it non-explicit, or try another model.",
    "retryable": false,
    "refunded": true,
    "detail": "La richiesta non ha superato il controllo di sicurezza dei contenuti. Modifica il prompt e riprova."
  }
}

code è la categoria generale (i quattro valori documentati sin dal lancio). reason indica il motivo esatto: usalo nel codice e mostra message e hint agli utenti. retryable indica se un nuovo invio della stessa richiesta può funzionare, param specifica il campo da modificare quando riusciamo a identificarlo e detail contiene la formulazione del fornitore del modello.

Gli errori causati dalla richiesta — content_blocked, un file rifiutato in invalid_input, input_unreachable — non vengono riprovati presso altri fornitori, perché verrebbero rifiutati di nuovo. Prima vengono riprovate le interruzioni del servizio e gli errori dei fornitori su tutti i percorsi idonei, allo stesso prezzo. Consulta Errori e rimborsi.

Se il servizio di generazione non riesce a scaricare uno dei file di input, di solito proviamo a scaricarlo noi. Se ci riusciamo, il job viene ripetuto usando una copia ospitata da noi, allo stesso prezzo e senza che tu debba fare nulla; la generazione continua a mostrare gli URL che hai inviato e la copia viene eliminata insieme alla generazione secondo il relativo periodo di conservazione. Quindi input_unreachable di solito significa che non è stato possibile scaricare affatto il file: richiede l'accesso, il link firmato è scaduto, non punta direttamente al file oppure il server che lo ospita ha rifiutato la richiesta. Copiamo immagini fino a 30 MB, video fino a 200 MB e audio fino a 50 MB; un file più grande o illeggibile genera l'errore invalid_input.

Riprovare in sicurezza#

Riprova 429, 500, 502 e 503 con backoff esponenziale e jitter. Non riprovare senza modifiche gli altri errori 4xx: falliranno allo stesso modo.

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

export async function postWithRetry(url, headers, body, attempts = 5) {
  let resp;
  for (let attempt = 0; attempt < attempts; attempt++) {
    resp = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
    if (!RETRYABLE.has(resp.status)) break;
    // exponential backoff with jitter: ~1s, 2s, 4s, 8s…
    await new Promise((r) => setTimeout(r, Math.min(2 ** attempt, 30) * 1000 + Math.random() * 1000));
  }
  const data = await resp.json();
  if (!resp.ok) throw new Error(`${resp.status} ${data.error.code}: ${data.error.message}`);
  return data;
}

import random, time, requests

RETRYABLE = {429, 500, 502, 503}

def post_with_retry(url, headers, json, attempts=5):
    for attempt in range(attempts):
        resp = requests.post(url, headers=headers, json=json, timeout=30)
        if resp.status_code not in RETRYABLE:
            break
        # exponential backoff with jitter: ~1s, 2s, 4s, 8s…
        time.sleep(min(2 ** attempt, 30) + random.random())
    if not resp.ok:
        err = resp.json()["error"]
        raise RuntimeError(f"{resp.status_code} {err['code']}: {err['message']}")
    return resp.json()

Esempi di convalida#

I messaggi di convalida indicano il campo e i valori consentiti, così puoi mostrarli direttamente agli sviluppatori:

[
  {
    "error": {
      "code": "invalid_request",
      "message": "\"prompt\" is required",
      "param": "prompt"
    }
  },
  {
    "error": {
      "code": "invalid_request",
      "message": "Unknown parameter \"resoluton\"",
      "param": "resoluton"
    }
  },
  {
    "error": {
      "code": "not_found",
      "message": "Unknown endpoint \"bytedance/seedance-2.0-fast/text-to-gif\". See GET /api/v1/models."
    }
  }
]

Puoi anche calcolare il prezzo senza eseguire la richiesta: POST /api/v1/quote/{endpoint} convalida i campi che incidono sul prezzo e restituisce il costo. Consulta il Riferimento API.