Fehler

Wenn ein Aufruf schiefgeht, liefert die Antwort eine Zahl (code), die sagt, welche Art Problem es ist, und einen Satz (msg) für Menschen. Verzweige nach der Zahl; den Satz zeigst oder loggst du.

Die Antworthülle

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

• code ist ein Geschäftscode. 200 heißt Erfolg, alles andere steht unten.
• Bei Fehlern gibt es kein data-Feld – außer bei einigen Fehlern der Asset-Bibliothek, die data.reason mitliefern.
• Auch der HTTP-Status ist gesetzt (40201 kommt mit HTTP 402). Verzweige nach einem der beiden, nicht nach einer Mischung – wir empfehlen das genauere code.
• request_id steht auch im Header X-Request-Id. Gib sie an, wenn du den Support kontaktierst.

Ist eine Antwort gar kein JSON – etwa eine HTML- oder Textseite aus dem Netz dazwischen –, behandle sie nach HTTP-Status und logge den Anfang des Bodys.

Sprache der Fehlermeldungen

msg und die errorMessage eines fehlgeschlagenen Tasks sind standardmäßig Englisch. Schick Accept-Language mit en, ja, ko, de, fr, es, pt-BR, ru, it oder pl oder stell die API-Fehlersprache in der Konsole ein, dann kommen sie in dieser Sprache; andere Sprachen fallen auf Englisch zurück. Fehlerantworten tragen Content-Language. Die Codes ändern sich nie mit der Sprache – noch ein Grund, msg niemals zu parsen.

Meldet ein Modell einen konkreten Grund (etwa ein unlesbares Referenzbild), gibt errorMessage diesen Grund auf Englisch weiter, ohne interne Details.

Allgemeine Codes

Guthaben und Limits

Berechtigungen

Ein einfaches 403 bei gültigem Schlüssel heißt, dass das Konto die API gerade nicht nutzen kann; melde dich mit der request_id beim Support.

Verfügbarkeit von Modellen

Beide erzeugen keinen Task und reservieren keine Credits.

Fehlercodes von Tasks

Ein angenommener Task, der danach scheitert, hat state: "failed" und einen dieser Werte in errorCode. Die Liste ist abgeschlossen: Behandle jeden anderen Wert wie upstream_failed.

Ein gescheiterter Task gibt seine Reservierung frei und kostet also nichts (einige wenige Modelle berechnen inhaltliche Ablehnungen und sagen das auf ihrer Seite). errorMessage erklärt den Grund in Worten; verzweige nur nach errorCode.

Wann sich ein 409 zu wiederholen lohnt

Die Wiederholung schreiben

Wiederhole nur, was beim zweiten Mal klappen kann, warte auf Retry-After, wenn es mitkommt, und sonst exponentiell:

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")

Wenn du createTask wiederholst, schick immer denselben Idempotency-Key – sonst wird eine Anfrage, die eigentlich durchging, doppelt ausgeführt und doppelt berechnet.

Fehlersuche

1. Notiere request_id und code.
2. Such den Task in den Logs der API-Konsole, per Task-ID oder request_id.
3. Kommst du nicht weiter? Kontaktiere den Support mit request_id, Uhrzeit (UTC) und code. Schick niemals deinen API-Schlüssel.