Errores

Cuando una llamada falla, la respuesta indica dos cosas: un número (code) que identifica el tipo de problema y una frase (msg) para que una persona la lea. Esta página enumera los números, sus significados y si reintentar puede ayudar. Si solo necesitas resolver un síntoma rápidamente, empieza por Solución de problemas.

Formato de la respuesta

Las respuestas JSON de la API nativa de tareas utilizan este formato: los mismos cuatro campos alrededor de cada respuesta. Interpreta las respuestas compatibles de /v1 y SSE según sus propios protocolos:

{ "code": 200, "msg": "success", "data": { }, "request_id": "req_…" }

• code es un código de negocio, no un estado HTTP. 200 significa éxito.
• En caso de fallo, data no aparece, en lugar de ser null: recibes code, msg y request_id. La única excepción: algunos fallos de la biblioteca de recursos añaden data.reason.
• msg es para personas: su redacción y su idioma pueden cambiar (véase más abajo). Nunca bases una condición en ese texto; usa code.
• request_id también se devuelve en el encabezado X-Request-Id. Indícalo al informar de un problema.

El estado HTTP también se establece correctamente. Puedes basar las condiciones en cualquiera de los dos, pero solo en uno: sus valores difieren para códigos concretos, como saldo insuficiente, que es code: 40201 con HTTP 402. Mezclarlos acabará dejando algún caso sin cubrir.

Recomendamos utilizar code. 404 solo puede indicar «no encontrado»; 40201 indica que el saldo disponible es insuficiente.

Idioma de los mensajes de error

El texto de error para personas puede llegar en el idioma que elijas. El predeterminado es inglés. Solo estos tres lugares siguen esa elección:

• msg en el formato de respuesta;
• errorMessage de una tarea fallida, tanto en recordInfo como en callbacks de webhook, con una excepción indicada a continuación;
• error.message en los objetos de error de endpoints compatibles, tanto con el formato de OpenAI o Anthropic como con el de Google Gemini (/v1beta).

Códigos de idioma admitidos: en, ja, ko, de, fr, es, pt-BR, ru, it, pl.

La excepción: si el propio modelo proporcionó un motivo concreto de fallo, como una imagen de referencia que no pudo leer o una restricción de derechos de autor sobre audio generado, errorMessage incluye ese motivo en inglés, sin detalles internos como nombres de servicios, hosts, URL e ID de solicitudes, para que veas qué falló realmente. Los motivos sobre el estado de cuenta o facturación nunca se transmiten; recibes nuestro mensaje. Content-Language sigue describiendo msg, y errorCode siempre es el valor que debes usar para las condiciones.

Elegir el idioma

Se utiliza la primera opción aplicable:

1. El encabezado de solicitud Accept-Language, solo para esa solicitud. Se aplica la ponderación HTTP estándar: elegimos el idioma reconocido con el mayor valor q. Las variantes regionales se asignan a su idioma: de-DE cuenta como de y pt-PT como pt-BR. No se ofrece chino, por lo que sus etiquetas no coinciden con ningún idioma y se prueba el siguiente candidato. * significa sin preferencia.
2. El ajuste de tu cuenta, en Configuración → Idioma de errores de API de la consola. Abarca todas las solicitudes con una clave de esa cuenta que no incluyan un Accept-Language reconocible. La mayoría de los SDK de servidor y curl no envían ese encabezado de forma predeterminada, por lo que es la opción usada por la mayoría de las integraciones. Los callbacks de webhook no tienen un encabezado de solicitud para elegir el idioma y siempre siguen el ajuste de cuenta.
3. En los demás casos, inglés.

Las respuestas de error incluyen un encabezado Content-Language con el idioma en el que se escribió realmente el mensaje.

Ejemplo

El mismo 40201, saldo insuficiente, llega en inglés de forma predeterminada:

HTTP/1.1 402 Payment Required
Content-Language: en

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

Añade un encabezado Accept-Language: ja; el resto es la misma llamada de creación de tarea de la guía de inicio:

curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

Ahora msg está en japonés; code sigue siendo 40201:

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

Códigos generales

503 y 50301 comparten estado HTTP, pero son códigos de negocio distintos: 503 se refiere a un servicio auxiliar y 50301 al propio modelo.

Distinguir los tres casos de 401

Tres errores distintos de autenticación devuelven 401 y se resuelven de formas diferentes. El code permanece en 401 en todos; msg permite distinguirlos.

El caso intermedio se decide sin consultar la base de datos; por eso puede indicar algo que el tercero no: esa cadena nunca pudo funcionar. El tercer mensaje es deliberadamente idéntico para una clave inexistente, revocada o vencida, de modo que no permite investigar qué claves existen.

Aquí se muestran las cadenas en inglés; msg sigue la selección de idioma anterior y su redacción no es un contrato. Basa las condiciones en code y trata el mensaje como algo que lees, muestras o registras, no como un patrón que debes comparar.

La cuenta no puede llamar a la API

La clave es válida en ambos casos siguientes; es la cuenta la que todavía no puede llamar a la API.

40310 significa que no se ha verificado el correo. El mensaje es Verify your account email to run models and call the API…:

1. Abre la consola. Un aviso superior indica que el correo no está verificado y permite enviar de nuevo el mensaje de verificación.
2. Sigue el enlace del correo de verificación; revisa también la carpeta de spam.
3. Reintenta la misma llamada. No hace falta una clave nueva.

La consola sigue funcionando mientras la API está bloqueada, así que todavía puedes consultar tu historial.

Un 403 simple con This account cannot call the API right now indica que la cuenta está restringida. Contacta con soporte e incluye el request_id.

Saldo y límites de gasto

Ninguno se resuelve reintentando: los saldos y límites no cambian porque vuelvas a preguntar. Consulta Límites de gasto.

Permisos

Ninguno de estos errores se resuelve reintentando.

Códigos de motivo de la biblioteca de recursos

Los fallos en los endpoints de la biblioteca de recursos (/api/v1/assets…) pueden añadir al envoltorio habitual un campo legible por máquina, data.reason:

{ "code": 400, "msg": "…", "data": { "reason": "asset_library_locked" }, "request_id": "req_…" }

code, el estado HTTP, msg y el errorCode de la tarea son los mismos con o sin motivo, así que tu gestión actual sigue funcionando. El motivo aparece solo en los endpoints de la biblioteca de recursos, nunca en otros endpoints nativos, y la capa compatible con OpenAI y las demás capas de compatibilidad conservan sus propias formas de error. La lista puede crecer: trata un valor desconocido como un motivo ausente.

Disponibilidad de los modelos

50301 significa que el modelo no pudo aceptar la tarea al enviarla: no está publicado, no tiene precios activos o no tiene capacidad de generación disponible. Los problemas temporales de capacidad pueden resolverse con reintentos limitados. Un modelo no disponible o un precio activo ausente no se arreglan repitiendo solicitudes. Actualiza el catálogo y pide confirmación al usuario antes de cambiar de modelo.

40004 y 50301 son deliberadamente distintos. 50301 significa que el modelo no puede aceptar ninguna tarea en este momento; esperar podría ayudar. 40004 significa que funciona, pero no puede servir esta combinación de ajustes; msg indica el ajuste entre paréntesis, por ejemplo This model cannot serve this parameter combination right now (…). Esperar no ayudará; cambiar un valor sí. Ninguno crea una tarea ni retiene dinero.

Códigos de fallo de tareas

Un fallo posterior a la aceptación aparece en errorCode de recordInfo. El conjunto es cerrado: aquí nunca aparecen diagnósticos internos, por lo que debes tratar cualquier valor fuera de la lista como upstream_failed.

Las tareas fallidas o vencidas normalmente liberan toda la retención. Algunos rechazos de contenido se cobran al precio aceptado únicamente si la página del modelo informa expresamente de esa excepción. Consulta settled y cost para conocer el cargo final. errorMessage es para personas: explica el motivo, puede citar en inglés la explicación del modelo (véase arriba) y su redacción cambia; basa las condiciones solo en errorCode. Aquí «reintentar» significa enviar una tarea nueva, que se cobra de nuevo si termina correctamente.

Qué errores cuestan dinero

La liquidación o liberación se completa automáticamente, incluso tras interrumpirse un proceso. Los fallos ordinarios liberan toda la retención; determinados rechazos de contenido indicados expresamente en la página del modelo se cobran al precio aceptado. Consulta la liquidación y el saldo para verificar el resultado; véase Facturación.

Cuándo conviene reintentar un 409

Implementar los reintentos

Usa espera exponencial con variación aleatoria para que un lote de fallos no vuelva a intentarlo al mismo instante:

// 409 is operation-specific and must be handled at the call site.
const RETRYABLE = new Set([429, 500, 503, 50301]);

async function callWithRetry(path, init, { attempts = 4 } = {}) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(`https://api.spicyapi.ai/api/v1${path}`, init);

    // A page from the edge network is not our JSON envelope
    if (!res.headers.get('content-type')?.includes('json')) {
      const text = await res.text();
      throw new Error(`HTTP ${res.status}, not JSON: ${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} (request_id=${body.request_id})`);
    }

    // When the server says how long to wait, trust it
    const retryAfter = Number(res.headers.get('retry-after'));
    const backoff = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter * 1000
      : 2 ** i * 1000 + Math.random() * 500;

    await new Promise((r) => setTimeout(r, backoff));
  }
  throw new Error('out of retries');
}

import random, time, requests

# 409 is operation-specific and must be handled at the call site.
RETRYABLE = {429, 500, 503, 50301}
BASE = "https://api.spicyapi.ai/api/v1"


def call_with_retry(method: str, path: str, attempts: int = 4, **kwargs) -> dict:
    for i in range(attempts):
        res = requests.request(method, f"{BASE}{path}", **kwargs)

        # A page from the edge network is not our JSON envelope
        try:
            body = res.json()
        except ValueError:
            raise RuntimeError(f"HTTP {res.status_code}, not JSON: {res.text[:200]}")

        if body["code"] == 200:
            return body["data"]
        if body["code"] not in RETRYABLE:
            raise RuntimeError(f'{body["code"]} {body["msg"]} (request_id={body.get("request_id")})')

        # When the server says how long to wait, trust it
        retry_after = res.headers.get("retry-after")
        backoff = float(retry_after) if retry_after else 2**i + random.random() * 0.5
        time.sleep(backoff)

    raise RuntimeError("out of retries")

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"math/rand"
	"net/http"
	"strconv"
	"time"
)

// retryable lists the codes worth another attempt. Anything else returns
// the same answer however many times you ask — and each ask eats your own
// rate limit.
// Whether the generation itself failed is read from recordInfo's state.
var retryable = map[int]bool{429: true, 500: true, 503: true, 50301: true}

type envelope struct {
	Code      int             `json:"code"`
	Msg       string          `json:"msg"`
	Data      json.RawMessage `json:"data"`
	RequestID string          `json:"request_id"`
}

func callWithRetry(newReq func() (*http.Request, error), attempts int, out any) error {
	for i := 0; i < attempts; i++ {
		req, err := newReq()
		if err != nil {
			return err
		}
		res, err := http.DefaultClient.Do(req)
		if err != nil {
			// Transport-level failure: the request may well have arrived.
			// On createTask, send the same Idempotency-Key or this retry
			// turns into a second generation and a second charge.
			time.Sleep(backoff(i, ""))
			continue
		}

		var env envelope
		decErr := json.NewDecoder(res.Body).Decode(&env)
		io.Copy(io.Discard, res.Body)
		res.Body.Close()
		if decErr != nil {
			// Not our JSON envelope, for example a page from the edge network.
			return fmt.Errorf("HTTP %d, response is not JSON: %w", res.StatusCode, decErr)
		}

		if env.Code == 200 {
			return json.Unmarshal(env.Data, out)
		}
		if !retryable[env.Code] {
			return fmt.Errorf("%d %s (request_id=%s)", env.Code, env.Msg, env.RequestID)
		}
		// When the server says how long to wait, trust it
		time.Sleep(backoff(i, res.Header.Get("Retry-After")))
	}
	return fmt.Errorf("out of retries")
}

// backoff trusts Retry-After when present, otherwise backs off
// exponentially with jitter so a batch of failures does not come back
// as one thundering herd.
func backoff(attempt int, retryAfter string) time.Duration {
	if s, err := strconv.Atoi(retryAfter); err == nil && s > 0 {
		return time.Duration(s) * time.Second
	}
	base := time.Duration(1<<attempt) * time.Second
	return base + time.Duration(rand.Intn(500))*time.Millisecond
}

Depuración

Si un error no tiene sentido, sigue esta lista:

1. request_id: con él podemos encontrar la solicitud exacta.
2. code: consulta las tablas anteriores.
3. Logs de la consola: pega el ID de tarea o request_id en el buscador de Logs para abrirla y ver estado, costo, latencia, clave que la envió, código de error y motivo. Los parámetros y resultados solo se muestran mientras se conservan y, dentro de un equipo, solo a roles autorizados a leer contenido.

El msg de 500 siempre es un mensaje genérico de «servicio temporalmente no disponible», sin detalles internos: nunca aparecen estructuras internas, nombres de componentes ni trazas de pila en una respuesta. Solo se pueden investigar con request_id.

Para contactarnos, abre una conversación en Soporte dentro de la consola o escribe a support@spicyapi.ai. Incluye el request_id o ID de tarea, la hora en UTC y el code. Nunca envíes una clave de API.