Błędy

Gdy wywołanie się nie uda, odpowiedź zawiera liczbę (code), która mówi, jaki to problem, oraz zdanie (msg) dla człowieka. Rozgałęziaj logikę według liczby; zdanie pokazuj albo zapisuj w logach.

Koperta

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

• code to kod biznesowy. 200 oznacza sukces; pozostałe są wypisane niżej.
• Przy błędzie nie ma pola data — wyjątkiem są niektóre błędy biblioteki zasobów, które dodają data.reason.
• Status HTTP też jest ustawiany poprawnie (40201 przychodzi z HTTP 402). Opieraj się na jednym z nich, bez mieszania — polecamy dokładniejszy code.
• request_id jest też w nagłówku X-Request-Id. Podaj go, pisząc do pomocy.

Jeśli odpowiedź w ogóle nie jest JSON-em — np. stroną HTML lub tekstową z sieci pośredniczącej — obsłuż ją według statusu HTTP i zapisz w logach początek treści.

Język komunikatów o błędach

msg i errorMessage nieudanego zadania są domyślnie po angielsku. Wyślij Accept-Language z wartością en, ja, ko, de, fr, es, pt-BR, ru, it lub pl albo ustaw język błędów API w konsoli, a dostaniesz je w tym języku; pozostałe języki wracają do angielskiego. Odpowiedzi z błędem mają nagłówek Content-Language. Kody nigdy nie zmieniają się z językiem — kolejny powód, by nigdy nie parsować msg.

Gdy model poda konkretny powód niepowodzenia (np. nieczytelny obraz referencyjny), errorMessage przekazuje go po angielsku, bez szczegółów wewnętrznych.

Kody ogólne

Saldo i limity

Uprawnienia

Zwykłe 403 przy ważnym kluczu oznacza, że konto nie może teraz korzystać z API; napisz do pomocy i podaj request_id.

Dostępność modeli

Żaden z nich nie tworzy zadania ani nie blokuje kredytów.

Kody niepowodzeń zadań

Zadanie przyjęte, które potem się nie powiodło, ma state: "failed" i jedną z tych wartości w errorCode. Lista jest zamknięta: każdą inną wartość traktuj jak upstream_failed.

Nieudane zadanie zwalnia blokadę, więc nic nie kosztuje (nieliczne modele pobierają opłatę za odmowę z powodu treści i piszą o tym na swojej stronie). errorMessage opisuje powód słowami; rozgałęziaj logikę tylko według errorCode.

Kiedy warto ponowić 409

Jak napisać ponowienie

Ponawiaj tylko to, co może się udać za drugim razem, czekaj na Retry-After, jeśli przyszedł, a w przeciwnym razie zwiększaj przerwę wykładniczo:

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

Ponawiając createTask, zawsze wysyłaj ten sam Idempotency-Key, żeby zapytanie, które w rzeczywistości się udało, nie zostało wykonane i rozliczone dwa razy.

Diagnozowanie

1. Zapisz request_id i code.
2. Znajdź zadanie w logach konsoli API po ID zadania lub request_id.
3. Nadal utknąłeś? Napisz do pomocy, podając request_id, godzinę (UTC) i code. Nigdy nie wysyłaj swojego klucza API.