Erros

Quando uma chamada falha, a resposta informa duas coisas: um número (code) que identifica o tipo de problema e uma frase (msg) para leitura humana. Esta página lista cada número, seu significado e se tentar novamente pode ajudar. Se você só precisa resolver um sintoma rapidamente, comece por Solução de problemas.

O envelope

Respostas JSON da API nativa de tarefas usam este envelope, com os mesmos quatro campos em cada resposta. Interprete respostas de compatibilidade /v1 e SSE conforme seus próprios protocolos:

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

• code é um código de negócio, não um status HTTP. 200 significa sucesso.
• Em falhas, data fica ausente, não null; você recebe code, msg e request_id. A única exceção: algumas falhas da biblioteca de ativos acrescentam data.reason.
• msg é para pessoas: a redação pode mudar, assim como o idioma; veja abaixo. Nunca baseie a lógica nela; use code.
• request_id também retorna no cabeçalho X-Request-Id. Informe-o ao relatar um problema.

O status HTTP também é definido corretamente. Baseie a lógica em um deles, mas somente em um: eles diferem nos códigos específicos, como saldo insuficiente, que é code: 40201 com HTTP 402. Misturar os dois acaba deixando algum caso sem tratamento.

Recomendamos usar code. 404 só diz “não encontrado”; 40201 informa que o saldo disponível é insuficiente.

Idioma das mensagens de erro

O texto de erro para leitura humana pode ser retornado no idioma escolhido por você. O padrão é inglês. Somente estes três campos seguem a escolha:

• msg no envelope de resposta;
• errorMessage de uma tarefa com falha, tanto em recordInfo quanto em callbacks de webhook, com uma exceção abaixo;
• error.message nos objetos de erro dos endpoints compatíveis, nos formatos OpenAI, Anthropic ou Google Gemini (/v1beta).

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

A exceção: quando o próprio modelo informa um motivo específico da falha, como uma imagem de referência que não conseguiu ler ou uma restrição de direitos autorais no áudio gerado, errorMessage apresenta esse motivo em inglês, sem detalhes internos como nomes de serviços, hosts, URLs e IDs de solicitação, para que você entenda o que aconteceu. Motivos que mencionam estado da conta ou faturamento nunca são repassados; você recebe nossa própria mensagem. Content-Language ainda descreve msg, e errorCode é sempre o valor para a lógica do seu programa.

Escolher o idioma

Vale a primeira opção aplicável:

1. Cabeçalho Accept-Language da solicitação, apenas para aquela chamada. Aplica-se a ponderação HTTP padrão: usamos o idioma reconhecido com maior valor q. Variantes regionais são agrupadas no idioma; de-DE conta como de, e pt-PT, como pt-BR. Chinês não é oferecido, portanto nenhuma etiqueta chinesa corresponde a um idioma, e o próximo candidato é tentado. * significa sem preferência.
2. Configuração da conta, em Configurações → Idioma dos erros da API no console. Ela abrange toda solicitação com uma chave de API da conta que não tenha um Accept-Language reconhecível. A maioria dos SDKs no servidor e o curl não envia esse cabeçalho por padrão; por isso, esta é a opção usada pela maioria das integrações. Callbacks de webhook não têm cabeçalho de solicitação para essa escolha e sempre seguem a configuração da conta.
3. Caso contrário, inglês.

Respostas de erro incluem um cabeçalho Content-Language que identifica o idioma efetivamente usado na mensagem.

Exemplo

O mesmo 40201, saldo insuficiente, retorna em inglês por padrão:

HTTP/1.1 402 Payment Required
Content-Language: en

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

Adicione um cabeçalho Accept-Language: ja; o restante é a mesma chamada de criação de tarefa dos primeiros passos:

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"

msg agora está em japonês; code continua sendo 40201:

HTTP/1.1 402 Payment Required
Content-Language: ja

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

Códigos gerais

503 e 50301 compartilham status HTTP, mas são códigos de negócio diferentes: 503 trata de um serviço de apoio; 50301, do próprio modelo.

Diferenciar os três erros 401

Três erros bem diferentes de autenticação retornam 401 e exigem correções diferentes. O code permanece 401 em todos; msg permite diferenciá-los.

O caso intermediário é identificado sem consultar o banco de dados; por isso, permite afirmar algo que o terceiro não permite: aquela string nunca poderia funcionar. A terceira mensagem é intencionalmente igual para uma chave inexistente, revogada ou expirada, para que a resposta não possa ser usada para investigar quais chaves existem.

As strings aqui aparecem em inglês; msg segue a escolha de idioma acima, e sua redação não faz parte do contrato. Baseie a lógica em code e use a mensagem para ler, exibir ou registrar, não para comparar com um texto fixo.

A conta não pode chamar a API

Nestes dois casos, a chave é válida; é a conta que ainda não pode chamar a API.

40310 significa e-mail ainda não verificado. A mensagem é Verify your account email to run models and call the API…:

1. Abra o console. Um aviso no topo informa que o e-mail não foi verificado e permite reenviar a mensagem de verificação.
2. Abra o link no e-mail de verificação; confira a pasta de spam.
3. Repita a mesma chamada. Não é necessário criar outra chave.

O console continua funcionando enquanto a API está bloqueada; você ainda pode consultar o histórico.

Um 403 simples com This account cannot call the API right now significa conta restrita. Contate o suporte com o request_id.

Saldo e limites

Não vale repetir nenhum dos dois: saldo e limites não mudam por você perguntar de novo. Veja Limites de gastos.

Permissões

Nenhum desses erros é resolvido por novas tentativas.

Códigos de motivo da biblioteca de ativos

Falhas nos endpoints da biblioteca de ativos (/api/v1/assets…) podem acrescentar ao envelope usual um campo legível por máquina, data.reason:

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

code, o status HTTP, msg e o errorCode da tarefa são os mesmos com ou sem motivo, então o seu tratamento atual continua funcionando. O motivo aparece só nos endpoints da biblioteca de ativos, nunca em outros endpoints nativos, e a camada compatível com OpenAI e as demais camadas de compatibilidade mantêm seus próprios formatos de erro. A lista pode crescer: trate um valor desconhecido como motivo ausente.

Disponibilidade dos modelos

50301 significa que o modelo não conseguiu aceitar a tarefa no momento do envio: ele não está listado, não tem preço ativo ou não dispõe de capacidade de geração naquele momento. Problemas temporários de capacidade podem ser resolvidos com tentativas limitadas. Um modelo indisponível ou sem preço ativo não é corrigido por solicitações repetidas. Atualize o catálogo e obtenha confirmação do usuário antes de trocar de modelo.

40004 e 50301 são intencionalmente diferentes. 50301 significa que o modelo não pode aceitar nenhuma tarefa agora; esperar pode ajudar. 40004 significa que funciona, mas não atende esta combinação de configurações, e msg indica o ajuste entre parênteses, como This model cannot serve this parameter combination right now (…). Esperar não ajuda; alterar um valor, sim. Nenhum dos dois cria tarefa nem reserva dinheiro.

Códigos de falha de tarefas

Uma falha após a aceitação aparece em errorCode de recordInfo. O conjunto é fechado: diagnósticos internos nunca aparecem aqui; trate qualquer valor fora da lista como upstream_failed.

Tarefas com falha ou expiradas normalmente liberam toda a reserva. Algumas recusas de conteúdo são cobradas pelo orçamento aceito somente quando a página do modelo informa expressamente essa exceção. Confira settled e cost para saber a cobrança final. errorMessage é para pessoas: explica o motivo em texto, pode citar em inglês o motivo do próprio modelo, conforme acima, e sua redação muda; baseie a lógica somente em errorCode. “Tentar novamente” aqui significa enviar outra tarefa, cobrada de novo se for bem-sucedida.

Quais erros custam dinheiro

A liquidação ou liberação é concluída automaticamente, inclusive após uma interrupção de processo. Falhas comuns liberam toda a reserva; algumas recusas de conteúdo expressamente informadas na página do modelo são cobradas pelo orçamento aceito. Confira a liquidação da tarefa e o saldo para verificar o resultado; veja Faturamento.

Quando vale repetir um 409

Implementar novas tentativas

Use espera exponencial com variação aleatória para que um lote de falhas não volte todo no mesmo 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
}

Diagnóstico

Quando um erro não fizer sentido, siga esta lista:

1. request_id: informe-o para que possamos localizar a solicitação exata.
2. code: consulte as tabelas acima.
3. Logs no console: cole o ID da tarefa ou request_id na busca da página Logs para abrir a tarefa: status, custo, latência, chave de envio, código de erro e motivo. Parâmetros e resultados só aparecem enquanto ainda estão retidos e, em uma equipe, somente para papéis com permissão de leitura de conteúdo.

O msg de 500 é sempre uma mensagem genérica de serviço temporariamente indisponível, sem detalhes internos: estrutura interna, nomes de componentes e stack traces nunca aparecem na resposta. Essas informações só podem ser investigadas por request_id.

Para falar conosco, abra uma conversa em Suporte no console ou envie e-mail para support@spicyapi.ai. Inclua request_id ou ID da tarefa, horário em UTC e code. Nunca envie uma chave de API.