Códigos de Erro da API Text-to-Video Explicados

A maioria das falhas em APIs text-to-video se resume a 5 grupos: requisições inválidas, problemas de autenticação, limites de taxa, bloqueios de segurança ou problemas no servidor. Se eu verificar o status HTTP, o corpo completo do erro, o ID da requisição ou da tarefa e o horário da falha, geralmente consigo encontrar a causa rapidamente.

Aqui está a versão resumida:

• Erros da série 400 geralmente significam que preciso corrigir a requisição.
• 401/403 costumam apontar para chave de API, acesso, cobrança ou regras de IP.
• 429 significa que atingi um limite de requisições, de jobs ou de gastos.
• 200 OK no envio não significa que o vídeo foi concluído. Ainda preciso consultar o job e verificar se está failed.
• Erros da série 500 muitas vezes exigem uma retentativa, mas somente depois de eu verificar se o job ainda está em execução.
• Bloqueios de segurança podem acontecer antes, durante ou depois da geração, e algumas APIs podem retornar menos clipes em vez de falhar o job inteiro.

Alguns números se destacam. Jobs de vídeo, como os que usam Sora 2, podem reservar uma GPU por 30–90 segundos, os timeouts do cliente podem precisar ser de mais de 10 minutos e um plano de retentativa comum é começar em 5 segundos, limitar em 60 segundos, parar após 3 tentativas.

Se eu quiser menos jobs com falha e menos cobranças duplicadas, mantenho o fluxo simples:

• Registrar o corpo do erro e o ID da tarefa
• Separar os erros na camada da API das falhas em nível de job
• Retentar apenas os casos 429 e 5xx
• Verificar o estado da tarefa antes de reenviar o mesmo job
• Fixar versões exatas de modelo em vez de usar aliases como latest

Mensagens de Erro de API para uma BOA Experiência do Desenvolvedor

Comparação Rápida

Simplificando: sucesso no envio não é sucesso na renderização. Eu trataria os resultados do polling como a fonte da verdade e usaria o payload do erro - não apenas o código de status - para decidir o que fazer em seguida.

Erros de requisição no lado do cliente: códigos da série 400 que você pode corrigir

Depois de registrar os detalhes do erro, o próximo passo é descobrir o que deu errado no lado da requisição. Comece pelo corpo do erro e depois relacione o código HTTP à correção.

400, 404, 413 e 415: o que cada código significa para requisições de vídeo

Cada código aponta para um tipo diferente de erro na requisição. Um 400 geralmente significa JSON malformado, campos obrigatórios ausentes ou tipos de parâmetro inválidos. Por exemplo, passar duration como string ("6") em vez de um inteiro (6) falhará na validação ^[4]. Um 404 significa que o ID do modelo ou o caminho do endpoint está errado, muitas vezes por causa de um pequeno erro de digitação como wan2.7 em vez de [wan-2.7](https://apimart.ai/ja/model/wan-2-7) or [wan-2.6](https://apimart.ai/model/wan-2-6) ^[7]. Um 413 aparece quando uma imagem ou vídeo de referência é maior que o limite de tamanho de upload ^[4][7]. Um 415 significa que o cabeçalho Content-Type está errado, ou que o formato do arquivo não é suportado pelo modelo ^[5].

Incompatibilidades de modelo e parâmetro que causam falhas de validação

Mesmo quando seu JSON está limpo, as requisições ainda podem falhar na validação porque os modelos não seguem todos as mesmas regras. Resolução, duração, proporção e limites de ativos podem mudar de um modelo para outro.

Veja o MiniMax-Hailuo-2.3. Ele suporta 10 segundos em 768p, mas se você solicitar 1080p, a duração máxima cai para 6 segundos ^[6]. As regras de ativos podem ser igualmente rígidas. O Kling 3.0 exige que as imagens de entrada tenham pelo menos 300 px em ambas as dimensões, com uma proporção entre 1:2,5 e 2,5:1. O Wan 2.7 exige que os vídeos de referência tenham entre 2 e 10 segundos e no máximo 100 MB ^[4][7].

Um 422 geralmente significa que seus parâmetros conflitam entre si. Por exemplo, o SkyReels V4 retorna 422 quando você combina campos de Image-to-Video e Omni na mesma requisição ^[8].

Um pequeno hábito pode economizar muito tempo: use strings de versão fixadas em vez de aliases genéricos. As regras de parâmetro podem mudar entre versões de modelo ^[3]. Se a validação ainda falhar, verifique os limites exatos do modelo antes de retentar.

Se a requisição for validada mas ainda assim falhar, passe em seguida para autenticação, limites de taxa e verificações de segurança.

Autenticação, permissões e limites de taxa

Depois que a validação passa, a maioria das falhas restantes se resume a três coisas: autenticação, permissões ou limites de taxa.

401 e 403: erros de chave de API e de acesso

Um erro 401 Unauthorized significa que a requisição não incluiu credenciais de autenticação válidas. As causas usuais são uma chave de API ausente, uma chave inválida, uma chave que foi desativada ou excluída, ou um cabeçalho Authorization quebrado ^[9][1][2].

Muitas APIs esperam:

Authorization: Bearer YOUR_API_KEY

Algumas plataformas usam x-api-key no lugar. Então, se o nome ou o formato do cabeçalho estiver errado, isso sozinho pode disparar um 401 ^[1][10].

Comece pelo básico. Verifique a variável de ambiente, certifique-se de que a chave ainda está ativa e confirme que sua configuração de CI/CD injeta os segredos corretamente em cada ambiente ^[3]. Também ajuda ler o corpo da resposta em vez de parar no código de status HTTP. Erros como invalid_api_key, token_expired ou account_banned geralmente dizem o que quebrou muito mais rápido ^[9][3].

Um 403 Forbidden significa que o servidor reconheceu você, mas ainda assim bloqueou a requisição. Isso normalmente aponta para um problema de acesso. Sua chave pode não ter o escopo de modelo correto, seu plano de conta pode não incluir aquele endpoint, seus créditos podem ter acabado, ou o IP da sua requisição pode não estar na lista de permissões ^[3][9].

O corpo da resposta também importa aqui. Se você vir insufficient_credits, olhe a cobrança. Se vir permission_error, verifique escopos, acesso ao modelo ou limites do plano. E se o acesso parecer correto mas o tráfego estiver alto demais, a próxima parada geralmente é o 429.

429: erros de limite de taxa e de cota excedida

Se a autenticação tiver sucesso, o volume de requisições costuma ser o próximo gargalo. Um erro 429 Too Many Requests significa que você atingiu um limite de throttle, um limite de concorrência ou um limite de gastos ^[3][9][10]. Em bom português: você enviou requisições demais em uma janela curta, executou jobs demais ao mesmo tempo, ou ultrapassou um teto de cobrança ^[3][9].

Mais uma vez, o corpo da resposta dá a melhor pista. rate_limit_exceeded geralmente significa que você deve usar backoff exponencial. spend_limit_exceeded significa que é hora de verificar as configurações de cobrança ^[3][9].

Enfileire jobs em lote localmente quando puder e fique de olho nestes cabeçalhos ^[2]:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset

Se você estiver usando o APIMart, uma única chave para todos os modelos pode reduzir o desvio de autenticação ^[3]. Ainda assim, o fluxo de depuração permanece praticamente o mesmo: leia o corpo da resposta, verifique suas variáveis de ambiente e certifique-se de que a conta pode acessar o modelo que você está chamando.

Bloqueios de segurança, timeouts e falhas no lado do servidor

Depois que a validação da requisição e a autenticação passam, as falhas que restam geralmente se enquadram em dois grupos: bloqueios de moderação e problemas no lado do servidor. Então, uma vez resolvidos autenticação, cota e validação, divida o resto da sua depuração nesses dois caminhos.

Erros de moderação e de política de conteúdo na geração de vídeo

Os bloqueios de segurança podem acontecer em três momentos diferentes: antes de a geração começar (a requisição é rejeitada de imediato), durante a renderização (o job é interrompido no meio do caminho), ou depois de o vídeo ser produzido (a saída é filtrada antes da entrega) ^[11]. Esse último caso confunde as pessoas. Um job pode terminar e ainda assim não entregar nada se o resultado for filtrado.

Com APIs baseadas em polling, o status HTTP pode ser enganoso. Você pode receber 200 OK na verificação de status, enquanto o corpo JSON diz state: "failed" e inclui um erro como SensitiveContentDetected ou NSFW ^[12]. Na prática, o corpo do polling é a fonte da verdade, não o código de status HTTP.

Se um bloqueio de moderação disparar, não retente exatamente o mesmo prompt. Reescreva-o. Uma redação de cinematografia simples e técnica pode ajudar a reduzir falsos positivos de filtros de segurança rigorosos ^[11]. Por exemplo:

• gimbal shot
• medium tracking shot
• golden hour lighting

Há outra sutileza aqui. Alguns modelos, incluindo o Google Veo, podem retornar menos clipes do que você pediu quando algumas saídas são bloqueadas por filtros de segurança, em vez de falhar o job inteiro ^[3]. Então não verifique apenas se a requisição foi concluída. Verifique se o número de ativos retornados corresponde ao número que você solicitou.

Se o prompt parecer limpo e o job ainda assim falhar, passe para a próxima camada: estabilidade do servidor.

500, 502, 503 e erros de timeout em jobs de vídeo assíncronos

As falhas no lado do servidor ficam em uma parte diferente do fluxo de depuração. Jobs de text-to-video muitas vezes reservam um slot de GPU por 30–90 segundos ^[3], o que os torna mais sensíveis a sobrecargas e timeouts.

Para os erros 500 e 504, verifique o status do job antes de retentar. Retentativas cegas podem criar renderizações duplicadas e dobrar seus custos ^[3]. Registre cada taskId ou prediction_id para poder consultar o endpoint de status diretamente antes de enviar um novo job ^[3][13].

Quando as retentativas são seguras, use backoff exponencial com jitter. Uma configuração prática é:

• começar em 5 segundos
• limitar em 60 segundos
• parar após 3 tentativas ^[13][12]

Defina os timeouts do cliente para 10 minutos ou mais ^[3] e crie alertas para valores crescentes de predict_time ^[3].

Um fluxo de depuração passo a passo para APIs text-to-video

Classifique o erro e então aplique a correção certa

Use este fluxo para ir do sintoma à correção em uma única passagem. Primeiro, leia o corpo completo da resposta. Depois, classifique a falha pelo código de status HTTP e pelo que o corpo do erro diz. Alguns provedores também enviam faixas internas de erro, mas seu guia principal deve ser o código de status HTTP e o corpo do erro ^[3][1].

Comece pelo corpo da resposta e depois enquadre o resultado em um destes grupos:

Depois que um job foi enviado, pare de pensar apenas em termos de respostas HTTP e olhe também para o estado da tarefa. Para jobs assíncronos, verifique na resposta do polling se há failed ou expired antes de enviar o mesmo job de novo. Esse único passo pode poupar você de custo extra e de muita confusão.

Antes de mexer no código, verifique a página de status do provedor. Se o serviço estiver degradado, a depuração local não vai dizer muito. Depois disso, inspecione os cabeçalhos de resposta x-deny-reason. Recusas em nível de proxy podem parecer erros de modelo se você pular essa verificação ^[3].

Além disso, fixe strings de versão de modelo exatas como kling-v3.0-std em vez de latest. Uma atualização silenciosa de modelo pode introduzir novas falhas de validação em um pipeline que funcionava perfeitamente no dia anterior ^[3].

Principais lições para integrações mais confiáveis

A maioria das falhas em APIs text-to-video segue alguns padrões repetíveis. Se você receber um erro 4xx, precisa mudar a requisição, as credenciais ou a configuração. Enviar a mesma chamada de novo geralmente não resolve nada.

• Registre as entradas da requisição: ID do modelo, hash do prompt e parâmetros (veja nossos tutoriais de API de IA para boas práticas de logging).
• Registre o ID da tarefa, o status final, o predict_time e a mensagem de erro completa.
• Retente apenas 429 e 5xx após verificar o estado da tarefa, para evitar renderizações duplicadas e custos dobrados ^[3].
• Monitore o predict_time em busca de picos - eles podem sinalizar precocemente a degradação da infraestrutura ^[3].

Perguntas Frequentes

Como sei se um job de vídeo realmente falhou?

Consulte o endpoint de status da tarefa com o ID da tarefa que você recebeu ao enviar o job. Se o campo status voltar como failed, o job não foi concluído.

Em seguida, olhe o campo error na resposta. Ele diz por que falhou, para que você possa decidir o que fazer a seguir:

• ajustar seu prompt
• verificar o saldo da sua conta
• esperar, se houver um problema de infraestrutura

Você também pode usar webhooks para receber notificações automáticas quando um job entra em estado de falha.

Quando devo retentar uma requisição de API text-to-video?

Retente erros transitórios como limites de taxa 429 e problemas no lado do servidor 500 com backoff exponencial. Isso desacelera as tentativas repetidas e ajuda você a evitar sobrecarregar o sistema.

Para um 504 Gateway Timeout ou uma falha de tarefa, verifique o status da tarefa antes de tentar de novo. Uma retentativa cega pode disparar renderizações duplicadas e adicionar custo extra.

Não retente erros 400 ou 401. Esses geralmente significam que a própria requisição precisa ser corrigida primeiro.

Por que um prompt seria bloqueado após o envio?

Um prompt costuma ser bloqueado porque esbarra nas regras de segurança ou moderação de um provedor. Isso pode acontecer bem na hora em que você o envia, ou mais tarde durante a geração, se o sistema detectar conteúdo visual ou de áudio proibido.

Gatilhos comuns incluem temas sensíveis, violência, menores ou material protegido por direitos autorais. E como os sistemas de moderação tendem a agir com cautela, até prompts inofensivos podem ser sinalizados.

Se isso acontecer, reescreva a requisição em uma linguagem mais neutra e descritiva.