Errores

Cuando una llamada falla, la respuesta te da un número (code) que dice qué tipo de problema es y una frase (msg) para que la lea una persona. Decide según el número; muestra o registra la frase.

El sobre

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

• code es un código de negocio. 200 significa éxito; todo lo demás está abajo.
• Si falla no hay campo data, salvo en algunos errores de la biblioteca de recursos, que añaden data.reason.
• El estado HTTP también se establece (40201 llega con HTTP 402). Decide con uno de los dos, no con una mezcla; te recomendamos code, que es más concreto.
• request_id también va en la cabecera X-Request-Id. Inclúyelo cuando escribas a soporte.

Si una respuesta ni siquiera es JSON —una página HTML o de texto de la red intermedia—, trátala según el estado HTTP y registra el principio del cuerpo.

Idioma de los mensajes de error

msg y el errorMessage de una tarea fallida vienen en inglés por defecto. Envía Accept-Language con en, ja, ko, de, fr, es, pt-BR, ru, it o pl, o configura el idioma de errores de la API en la consola, para recibirlos en ese idioma; el resto vuelve al inglés. Las respuestas de error llevan Content-Language. Los códigos nunca cambian con el idioma: otra razón para no analizar nunca msg.

Cuando un modelo da un motivo concreto de fallo (por ejemplo, una imagen de referencia ilegible), errorMessage lo transmite en inglés, sin detalles internos.

Códigos generales

Saldo y topes

Permisos

Un 403 sin más con una clave válida significa que la cuenta no puede usar la API ahora mismo; contacta con soporte con el request_id.

Disponibilidad de modelos

Ninguno de los dos crea una tarea ni retiene créditos.

Códigos de fallo de tareas

Una tarea aceptada que luego falla tiene state: "failed" y uno de estos valores en errorCode. La lista es cerrada: trata cualquier otro valor como upstream_failed.

Una tarea fallida libera su retención, así que no cuesta nada (unos pocos modelos cobran los rechazos por contenido y lo indican en su página). errorMessage explica el motivo con palabras; decide solo según errorCode.

Cuándo vale la pena reintentar un 409

Cómo escribir el reintento

Reintenta solo lo que puede salir bien a la segunda, espera Retry-After cuando venga y, si no, aumenta la espera de forma exponencial:

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

Al reintentar createTask, envía siempre el mismo Idempotency-Key, para que una solicitud que en realidad funcionó no se ejecute ni se cobre dos veces.

Depuración

1. Apunta el request_id y el code.
2. Busca la tarea en los logs de la consola de la API, por ID de tarea o request_id.
3. ¿Sigues atascado? Contacta con soporte con el request_id, la hora (UTC) y el code. Nunca envíes tu clave de API.