Erros

Quando uma chamada dá errado, a resposta traz um número (code) que diz o tipo de problema e uma frase (msg) para uma pessoa ler. Decida pelo número; mostre ou registre a frase.

O envelope

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

• code é um código de negócio. 200 significa sucesso; todo o resto está abaixo.
• Em caso de falha não há campo data, exceto em alguns erros da biblioteca de assets, que acrescentam data.reason.
• O status HTTP também vem certo (40201 chega com HTTP 402). Decida por um dos dois, sem misturar — recomendamos o code, que é mais específico.
• request_id também vai no cabeçalho X-Request-Id. Informe-o ao falar com o suporte.

Se a resposta nem for JSON — uma página HTML ou de texto da rede no meio do caminho —, trate pelo status HTTP e registre o começo do corpo.

Idioma das mensagens de erro

msg e o errorMessage de uma tarefa com falha vêm em inglês por padrão. Envie Accept-Language com en, ja, ko, de, fr, es, pt-BR, ru, it ou pl, ou defina o idioma de erros da API no console, para recebê-los nesse idioma; os demais voltam ao inglês. Respostas de erro trazem Content-Language. Os códigos nunca mudam com o idioma — mais um motivo para nunca interpretar o msg.

Quando um modelo informa um motivo específico de falha (por exemplo, uma imagem de referência ilegível), o errorMessage repassa esse motivo em inglês, sem detalhes internos.

Códigos gerais

Saldo e limites

Permissões

Um 403 simples com chave válida significa que a conta não pode usar a API no momento; fale com o suporte informando o request_id.

Disponibilidade de modelos

Nenhum dos dois cria tarefa nem reserva créditos.

Códigos de falha de tarefas

Uma tarefa aceita que depois falha tem state: "failed" e um destes valores em errorCode. A lista é fechada: trate qualquer outro valor como upstream_failed.

Uma tarefa com falha libera a reserva e não custa nada (alguns poucos modelos cobram recusas de conteúdo e avisam na própria página). O errorMessage explica o motivo em palavras; decida só pelo errorCode.

Quando vale repetir um 409

Escrevendo a nova tentativa

Repita só o que pode dar certo na segunda vez, espere Retry-After quando ele vier e, se não vier, aumente a espera exponencialmente:

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

Ao repetir createTask, envie sempre o mesmo Idempotency-Key, para que uma requisição que na verdade deu certo não seja executada nem cobrada duas vezes.

Depuração

1. Anote o request_id e o code.
2. Procure a tarefa nos logs do console da API, pelo ID da tarefa ou pelo request_id.
3. Ainda travado? Fale com o suporte com o request_id, o horário (UTC) e o code. Nunca envie sua chave de API.