Ошибки

Если вызов не удался, ответ содержит число (code), которое говорит, что это за проблема, и фразу (msg) для человека. Ветвитесь по числу, а фразу показывайте или пишите в лог.

Обёртка ответа

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

• code — бизнес-код. 200 означает успех, всё остальное перечислено ниже.
• При ошибке поля data нет — кроме нескольких ошибок библиотеки ассетов, которые добавляют data.reason.
• HTTP-статус тоже выставляется корректно (40201 приходит с HTTP 402). Ветвитесь по чему-то одному, не смешивая; мы советуем более точный code.
• request_id дублируется в заголовке X-Request-Id. Указывайте его при обращении в поддержку.

Если ответ вообще не JSON — например, HTML или текстовая страница от промежуточной сети, — обрабатывайте его по HTTP-статусу и пишите в лог начало тела.

Язык сообщений об ошибках

msg и errorMessage упавшей задачи по умолчанию на английском. Отправьте Accept-Language со значением en, ja, ko, de, fr, es, pt-BR, ru, it или pl либо выберите язык ошибок API в консоли — и получите их на этом языке; для остальных языков вернётся английский. В ответах с ошибкой есть заголовок Content-Language. Коды от языка не зависят — ещё одна причина никогда не разбирать msg.

Если модель сообщила конкретную причину сбоя (например, нечитаемое референсное изображение), errorMessage передаёт её на английском, без внутренних подробностей.

Общие коды

Баланс и лимиты

Права

Простой 403 при действующем ключе означает, что аккаунт сейчас не может пользоваться API; напишите в поддержку и приложите request_id.

Доступность моделей

Ни один из этих кодов не создаёт задачу и не резервирует кредиты.

Коды сбоя задач

У принятой, но затем упавшей задачи state: "failed", а в errorCode — одно из значений ниже. Список закрыт: любое другое значение обрабатывайте как upstream_failed.

Упавшая задача освобождает резерв, поэтому ничего не стоит (несколько моделей берут плату за отказ по содержанию и пишут об этом на своей странице). errorMessage объясняет причину словами; ветвитесь только по errorCode.

Когда стоит повторять 409

Как писать повтор

Повторяйте только то, что может получиться со второй попытки, ждите Retry-After, если он есть, а иначе увеличивайте паузу экспоненциально:

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

Повторяя createTask, всегда отправляйте тот же Idempotency-Key, чтобы запрос, который на самом деле прошёл, не выполнился и не списался дважды.

Отладка

1. Запишите request_id и code.
2. Найдите задачу в логах API-консоли по ID задачи или request_id.
3. Не помогло? Напишите в поддержку: request_id, время (UTC) и code. Никогда не отправляйте свой API-ключ.