Solução de problemas e recuperação

Cada seção abaixo parte do que você está vendo, explica a causa mais comum e diz o que fazer. Para o significado completo de cada número de erro, veja Erros; esta página é a companheira que responde "e agora?".

Encontre o seu problema

Guarde as evidências certas

Antes de mudar qualquer coisa, anote o que aconteceu. Isso acelera cada passo abaixo, e é exatamente o que o suporte precisa:

• O horário, em UTC se possível.
• O endpoint que você chamou, por exemplo POST /api/v1/jobs/createTask.
• O status HTTP e o code do corpo da resposta.
• O request_id: ele está no corpo da resposta e no cabeçalho de resposta X-Request-Id.
• O ID da tarefa, se você recebeu um. Ele começa com job_ e também aparece na página Registros do console.

Separe três situações, porque cada uma pede uma ação diferente: a API recusou explicitamente a requisição (você recebeu um erro em JSON — nada foi criado nem cobrado); você não recebeu resposta nenhuma (tempo limite estourado ou conexão caída — a tarefa pode existir; veja mais abaixo); ou a tarefa foi aceita e falhou depois (você tem um ID de tarefa com state: "failed").

Se uma resposta não é JSON — por exemplo, uma página HTML ou de texto simples —, ela veio da nossa rede de borda antes de chegar à API. Anote o status HTTP e as primeiras linhas do corpo. Uma página 403 desse tipo costuma significar que a requisição vem de uma região que não podemos atender; tentar de novo não muda nada.

Nunca coloque chaves de API, senhas, prompts completos ou arquivos originais em logs gerais ou em pedidos de suporte.

Paguei, mas o saldo não mudou

• Cartão: o saldo só muda depois que a confirmação da processadora de pagamentos chega até nós, normalmente em segundos. Atualize Faturamento e confira Pedidos de recarga.
• Cripto: o saldo é adicionado depois que a rede confirma a transação, normalmente em alguns minutos. Um pagamento menor que o valor mostrado, ou feito depois que a página de pagamento expirou, não é adicionado automaticamente.
• Transferência manual: abra o pedido em Pedidos de recarga e envie a referência bancária ou o hash da transação. A conferência é feita à mão, normalmente em poucas horas.

A lista completa de casos está em Prepare sua conta → Problemas comuns. O saldo continua sem aparecer? Abra uma conversa em Suporte (assunto Faturamento) com o ID do pedido e, para cripto, o hash da transação. Nunca envie números de cartão nem senhas.

Toda chamada retorna 401 ou 403

Comece por uma chamada que é gratuita e não altera nada — ler o seu saldo:

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

A primeira linha deve mostrar sk-spicy-. Se não mostrar nada, a chave não está carregada neste terminal — defina-a de novo (veja Prepare sua conta). Depois, leia o msg da resposta:

Nenhum desses casos melhora com novas tentativas.

Saldo, limites e suporte

• 40201 — o saldo disponível não cobre o preço estimado da tarefa. Adicione saldo (veja Prepare sua conta) e depois envie a mesma requisição de novo, com o mesmo Idempotency-Key. Uma verba promocional só paga os modelos que ela cobre.
• 40202 — um limite de gasto foi atingido; o msg diz qual. Um limite da chave (This key has reached its …) é aumentado em Chaves de API → Editar, ou recomeça sozinho (o diário às 00:00 UTC, o mensal no dia 1º, o acumulado nunca). Um limite da equipe (Workspace … budget has been reached) é aumentado na página Equipe por um proprietário, administrador ou gestor de orçamento. O limite da plataforma (Platform quota for today is exhausted…) não pode ser aumentado; tente de novo depois das 00:00 UTC. Veja Limites de gasto.
• 429 — requisições demais. Espere o número de segundos indicado em Retry-After e diminua o ritmo; o que mais ajuda é trocar o polling em ciclos apertados por webhooks. Se a mensagem for Too many pending uploads…, esperar não adianta: termine os uploads que você já começou. Veja Limites de requisição.

Falar com o suporte: abra uma conversa em Suporte, no console, ou escreva para support@spicyapi.ai. Inclua as evidências de mais acima: horário, endpoint, code, request_id ou ID da tarefa, o que você esperava e o que aconteceu, e a estrutura da sua requisição sem os valores privados. Nunca envie uma chave de API.

Modelo ausente ou indisponível

• O modelo não está na sua lista, ou você recebe 404: chame GET /api/v1/models com a sua chave de API e use um modelo cujos enabled e available sejam ambos true, copiando o ID dele exatamente. Uma página de modelo no site não prova que a sua chave pode chamá-lo agora. Veja Catálogo de modelos e schemas.
• 50301 — o modelo não está recebendo tarefas neste momento. Tente de novo algumas vezes, com pausas cada vez maiores, e depois pare; insistir não faz um modelo indisponível voltar. Atualize o catálogo e pergunte a quem paga antes de trocar de modelo.
• 40004 — o modelo funciona, mas não com esta combinação de configurações. O msg indica a configuração entre parênteses. Mude esse valor (por exemplo, uma resolução ou uma proporção de tela) em vez de tentar de novo.
• 40301 — o modelo existe, mas esta chave não tem permissão para usá-lo; edite os modelos permitidos da chave.

Entrada inválida ou conflito de cotação

• 400 — compare o seu input com o inputSchema atual do modelo no catálogo: nomes de campos, tipos, valores permitidos e exigências condicionais. Remova os campos que o modelo não lista. Confira de novo depois de trocar de modelo, porque cada modelo tem o próprio schema.
• 40003 — um arquivo enviado não bate com o que você declarou ao pedir a URL de upload. Peça uma nova URL de upload com o contentType e o tamanho corretos e envie o arquivo de novo.
• 413 — o corpo da requisição é grande demais. Envie a mídia pelo fluxo de mídia em vez de embuti-la.
• 40901 — a cotação expirou, a requisição mudou depois de cotada ou o preço mudou. Peça uma nova cotação, mostre o novo valor a quem paga e confirme de novo. Veja Cotações.
• Outros 409 — trate conforme a operação. Uma chave já usada com outro conteúdo precisa de um Idempotency-Key novo e correto para a nova requisição, e não de tentativas sem fim. Veja Erros.

Envio estourou o tempo limite sem ID de tarefa

Um tempo limite estourado não diz se a tarefa foi criada. Não se limite a enviar de novo com uma chave nova — isso pode criar uma segunda tarefa e uma segunda cobrança.

Tempo limite estourado no cliente, aba do navegador fechada ou stream desconectado não cancelam uma tarefa aceita, e uma tarefa aceita não pode ser cancelada.

A tarefa falhou

Tarefas que falham ou expiram 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 explicitamente essa exceção. Confira settled e cost para saber o valor final.

• Não tente de novo sem mudar nada: invalid_request, unsupported_combination, content_rejected (o modelo escolhido recusou o conteúdo — mude o prompt ou o modelo).
• Vale tentar de novo depois de uma pausa: rate_limited, upstream_unavailable, upstream_failed.
• Corrija antes: invalid_asset (envie o arquivo de novo), timeout (tente uma duração menor ou uma resolução mais baixa), generation_failed (as mesmas entradas costumam falhar do mesmo jeito).

errorMessage explica o motivo para pessoas; pode ser o motivo dado pelo próprio modelo, em inglês. Faça o seu código decidir apenas pelo errorCode. A tabela completa está em Erros. Uma nova tentativa é uma tarefa nova e é cobrada de novo se der certo.

A tarefa fica em queued ou running

Gerar leva tempo — um vídeo longo pode levar vários minutos. Toda tarefa tem um prazo no servidor, que recordInfo retorna como deadlineAt:

• Antes do deadlineAt: continue esperando o callback, ou consulte recordInfo com pausas cada vez maiores (não a cada segundo).
• Depois do prazo: a tarefa termina sozinha como expired, com errorCode: "timeout", e a reserva dela é devolvida por inteiro. Você não precisa cancelar nada — e tarefas aceitas não podem ser canceladas.

Se uma tarefa continuar em running bem depois do deadlineAt, fale com o suporte informando o ID da tarefa.

O upload deu certo, mas a entrada é recusada

• Você pulou a confirmação (commit). Um PUT bem-sucedido do arquivo não basta: chame files/{fileId}/commit e depois passe o URI spicy:// retornado no campo de entrada do modelo. Nunca passe o próprio uploadUrl.
• O arquivo não bate com o ticket. Confira o Content-Type, o tamanho e o formato declarados; qualquer divergência retorna 40003.
• Ele expirou. Um arquivo enviado pode ser usado até o expiresAt da resposta da confirmação — 1 dia por padrão, ou menos se a sua conta apagar os uploads quando a tarefa termina. Por isso, repetir uma tarefa pode exigir um upload novo.
• Ele pertence a outra conta. Um URI spicy:// só funciona com chaves da conta que fez o upload.

Veja Mídia para o fluxo completo de upload.

Callback que não chegou ou download expirado

Nenhum callback chegou:

1. Confira se o callBackUrl é um endereço https:// acessível pela internet. http:// simples não é aceito.
2. Confira se o seu receptor verifica a assinatura sobre os bytes originais da requisição, antes de qualquer interpretação do JSON, e responde rápido com um 2xx. Trabalho demorado vai para a sua própria fila. Se a chave de assinatura foi rotacionada recentemente, o receptor precisa usar a nova: não existe período de sobreposição. Veja Webhooks.
3. Consulte o histórico de entregas em Webhooks, no console, onde também dá para repetir uma entrega.
4. Enquanto isso, leia a tarefa com recordInfo — o polling sempre funciona como plano B. Veja Webhooks.

Callbacks podem chegar mais de uma vez ou com atraso, então elimine duplicatas antes de atender um pedido.

O link de download ou o arquivo sumiu:

• Um link de download dura 20 minutos. Se o resultado ainda estiver guardado, basta pedir um link novo; atualizar um link antigo não funciona.
• Se o resultado ainda estiver sendo copiado para o armazenamento, espere alguns segundos e peça de novo.
• Os resultados ficam guardados por no máximo cerca de 14 dias, e por menos tempo se a sua conta usar uma configuração de retenção mais curta. Quando contentState for expired ou purged, o arquivo não pode ser recuperado — rode o modelo de novo. Veja Retenção e destruição.

O stream termina antes da hora

Confira o status HTTP e o Content-Type antes de interpretar o stream conforme o seu protocolo. Pedaços que chegam pela rede não são eventos completos, e uma conexão fechada não é sinal de sucesso: procure o evento final do protocolo, qualquer evento de erro e o prazo da sua própria aplicação. Não suponha que um stream desconectado saiu de graça ou pode ser reenviado sem custo — o uso válido registrado antes da desconexão pode ser cobrado. Guarde o request_id e confira os seus registros de consumo. Veja Texto e streaming.

Permissões de equipe

• Você não consegue criar uma chave. O seletor de escopo no topo da barra lateral esquerda do console está numa equipe em que a sua função é Gestor de orçamento ou Somente leitura. Criar chaves exige a função Proprietário, Administrador ou Desenvolvedor. Troque para o seu escopo Pessoal, ou peça a um administrador da equipe a função Desenvolvedor.
• Você vê uma tarefa, mas não o prompt nem o resultado dela. Gestores de orçamento e membros Somente leitura veem apenas estado, custo e consumo.
• Você não consegue aceitar um convite. Entre com exatamente o endereço de e-mail para o qual o convite foi enviado. Convites expiram depois de 7 dias; se o seu expirou, peça outro.
• Uma chave da equipe parou com 40201. Chaves da equipe gastam o saldo do proprietário da equipe, então é o proprietário quem precisa adicionar saldo.

Veja Console e equipes para funções e limites de equipe.

Não consigo emitir uma fatura

• Os seus dados estão incompletos. Uma fatura precisa de um nome (da sua empresa ou o seu), da linha 1 do endereço, da cidade e do país, informados uma única vez no topo de Faturamento → Faturas.
• Um caractere não pode ser impresso. Só caracteres latinos, gregos e cirílicos podem aparecer numa fatura. Escreva um nome de empresa japonês ou coreano na forma romanizada com que ele foi registrado.
• Ela já existe. Cada recarga paga e cada mês encerrado podem ser faturados uma vez; baixe o documento que já existe. Para corrigir dados, escolha Emitir de novo nele.
• O mês não está disponível. Só meses já encerrados, e em que você gastou alguma coisa, podem ter um extrato de uso.

Veja Cobrança.

Fluxos relacionados

Erros · Integração em produção · Idempotência · Mídia · Webhooks · Texto e streaming · Prepare sua conta