Olá, sou a Dora—quebro APIs para diversão para que você não tenha que fazer isso.

Fiquei recebendo erros 401 na semana passada. Não do tipo misterioso—do tipo estúpido, onde você sabe que algo está errado mas não consegue ver. Descobri que tinha estado usando X-API-Key nos meus headers. WaveSpeed quer Authorization: Bearer. Pequena diferença. Duas horas perdidas.

É assim que funciona a autenticação de API—funciona silenciosamente quando está certa, e falha alto quando não está. E WaveSpeed, como a maioria das APIs modernas, não oferece muita margem de manobra. É o que aprendi usando a API do WaveSpeed para geração de imagens e vídeos nos últimos meses—e o que realmente ajudou quando as coisas quebraram.

Como a Autenticação da API WaveSpeed Realmente Funciona

WaveSpeed usa autenticação de token Bearer. Cada solicitação precisa de:

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

O formato é direto:

Authorization: Bearer your_api_key_here
Content-Type: application/json

Já vi pessoas tentarem X-API-Key, Api-Key, ou envolvê-la em aspas. A documentação oficial do WaveSpeed e os exemplos consistentemente mostram o formato de token Bearer. É isso. Sem variações.

Obtendo Sua Chave de API

Sua chave de API fica no painel do WaveSpeed em wavespeed.ai/accesskey. Você precisa adicionar créditos à sua conta antes de gerar uma—não há chave para usuários de nível gratuito. Quando você copia a chave, observe espaços em branco extras. Já fiz isso duas vezes—peguei um espaço no final e passei 20 minutos depurando antes de notar.

Fluxo de Autenticação para a API WaveSpeed

Não há atualização de token, sem OAuth, sem etapas intermediárias. Você envia o token Bearer, WaveSpeed o valida, sua solicitação ou prossegue ou é rejeitada com um 401. Se a autenticação falhar, você recebe uma resposta 401 imediatamente. O erro geralmente diz “invalid authentication” e diz para você verificar sua chave.

Tratando Erros 401 Não Autorizado

Um 401 do WaveSpeed significa que ele olhou para seu header Authorization e disse “Não reconheço isso.”

Lista de verificação de causas comuns

Os suspeitos usuais:

Formato de header errado (não usando Authorization: Bearer)
Chave de API copiada com espaços à direita ou quebras de linha
Chave regenerada no painel mas chave antiga ainda no código
Variável de ambiente não carregando
Sem top-up de conta—chaves não serão geradas sem adicionar créditos antes

Correções Rápidas

Quando obtenho um 401, começo aqui: Primeiro, registre exatamente o header. Não o que acho que estou enviando—o que realmente está na solicitação HTTP. Frequentemente o token Bearer é malformado ou o nome do header está ligeiramente errado. Segundo, copie a chave fresca do painel. Teste-a imediatamente com curl antes de colocá-la no código:

curl -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/flux-dev" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "test"}'

Se curl funcionar, o problema está no meu código de aplicação. Se curl falhar, a chave em si está errada. Terceiro, verifique o saldo da conta. WaveSpeed opera em um modelo baseado em crédito—se seu saldo chegar a zero, as chamadas de API podem falhar.

Gerenciando Respostas de Limite de Taxa 429

Os limites de taxa do WaveSpeed são em camadas: Bronze (limites básicos, top-up de $100), Silver (concorrência mais alta, top-up de $1.000), e Gold (customizado, $10.000+). Cada camada tem limites de throughput e tarefas simultâneas diferentes.

Os detalhes não estão documentados publicamente em números exatos, mas o padrão é claro: envie muitas solicitações muito rapidamente, obtenha um 429.

Entendendo Limites de Taxa

De acordo com o FAQ, limites de exemplo incluem Bronze com 10 imagens / 5 vídeos por minuto com máximo 3 tarefas simultâneas, Silver com 500 imagens / 60 vídeos por minuto com máximo 100 simultâneas, e **Gold com 2000 imagens / 120 vídeos por minuto com máximo 200 simultâneas.

Se você está recebendo erros “Too Many Requests”, provavelmente está atingindo seu limite de camada. Para evitar limitação, considere atualizar seu plano.

Estratégia de backoff exponencial para tentativas

Quando obtenho um 429, aguardo antes de tentar novamente. Não imediatamente—isso apenas me dá outro 429. Uso backoff exponencial:

Primeira tentativa: aguarde 1 segundo
Segunda tentativa: aguarde 2 segundos
Terceira tentativa: aguarde 4 segundos
Após três tentativas, pare e registre a falha

Muitas APIs incluem um header Retry-After que diz exatamente quanto tempo aguardar. Verifique-o e use esse valor quando disponível.

Projetando uma fila de solicitações do lado do cliente

Para operações em massa—como gerar 100 imagens em um trabalho em lote—adicionei uma fila que respeita meus limites de camada:

Rastreie quantas solicitações enviei na janela de tempo atual
Uma vez que me aproximo do limite (digamos, 90% do throughput da minha camada), pause novas solicitações
Retome quando a janela de tempo redefine

Isso evita a maioria dos 429s antes que aconteçam. Ainda os atinjo ocasionalmente quando vários processos são executados simultaneamente, mas a lógica de retentativa lida com aqueles.

Lidando com Erros 5xx do Servidor

Erros de servidor são diferentes. Um 401 ou 429 é eu fazendo algo errado. Um 500 ou 503 do WaveSpeed significa que algo quebrou do lado deles.

Padrões de Retentativa Seguros

Para erros 5xx, é seguro tentar novamente—a maioria dos erros de servidor é resolvida em segundos. Um bom padrão da documentação da Microsoft é tentar novamente imediatamente uma vez caso seja um erro transitório, então voltar ao backoff exponencial se persistir.

Minha abordagem:

Tente novamente imediatamente uma vez (talvez tenha sido um hiccup)
Se isso falhar, use o mesmo backoff exponencial que os 429s
Limitar em três retentativas totais
Registre a falha e prossiga

Para solicitações GET (verificando status de geração), tentar novamente é sempre seguro. Para solicitações POST (iniciando uma nova geração), sou mais cauteloso—não quero acidentalmente iniciar o mesmo trabalho duas vezes.

Configurando timeouts efetivamente

Defino dois timeouts:

Timeout de conexão: 5 segundos
Timeout de leitura: 30 segundos

WaveSpeed visa “menos de 2 segundos” para imagens e “cerca de 2 minutos” para vídeo, embora os tempos reais dependam do modelo, resolução e carga.

A maioria das gerações de imagem termina em menos de 5 segundos. Vídeo leva mais tempo—às vezes 60–90 segundos. Mas vi picos ocasionais para 20+ segundos mesmo para imagens.

Sem timeouts, uma solicitação lenta poderia ficar pendurada indefinidamente. Com eles, obtenho um erro limpo e posso tentar novamente.

Logging & Observabilidade na API WaveSpeed

Uma vez que a autenticação e o tratamento de erros funcionavam, precisava saber que estavam continuando a funcionar.

O que Registrar

Para cada chamada da API WaveSpeed, registro:

O endpoint do modelo sendo chamado
Código de status HTTP
Tempo de resposta em milissegundos
Se foi uma retentativa, e qual número da tentativa

Ao entrar em contato com o suporte do WaveSpeed sobre solicitações falhadas, eles pedem IDs de trabalho e timestamps. Mantenha-os em seus logs para depuração.

Limiares de Alerta

Defino alertas para:

Taxa de erro 401 acima de 1% (autenticação está quebrada)
Taxa de erro 429 acima de 5% (atingindo limites de taxa consistentemente)
Qualquer erro 5xx (deve ser raro)
Tempo de resposta médio acima de 10 segundos (possíveis problemas de desempenho)

Estes não são limiares universais—são o que fazia sentido para meu uso. O importante é ter algum limiar que dispare investigação antes que os usuários percebam.

Lista de Verificação de Produção da Autenticação da API WaveSpeed

Antes de entrar em produção:

Chaves de API armazenadas em variáveis de ambiente, não no código
Usando formato Authorization: Bearer corretamente
Header Content-Type definido como application/json
Lógica de retentativa com backoff exponencial para 429 e 5xx
Timeouts configurados (5s de conexão, 30s de leitura)
Logging inclui códigos de status, tempos de resposta, IDs de trabalho
Alertas configurados para picos de taxa de erro
Limitação de taxa do lado do cliente para permanecer dentro dos limites de camada
Monitoramento de saldo integrado para rastrear uso de crédito

Ainda obtenho 429s ocasionalmente durante picos de tráfego. E vi alguns erros 5xx quando o WaveSpeed teve breves problemas mês passado. Mas com essa configuração, esses erros não se cascata.

A autenticação funciona principalmente apenas funcionando. O esforço vai para lidar com as vezes que não funciona—limpa, previsível, sem me acordar às 2 da manhã porque o saldo de crédito chegou a zero.

💡 Enfrentando um problema? Poste o código de erro + ID da solicitação nos comentários, e nós o orientaremos através da lista de verificação de solução de problemas para ajudar a identificar a causa raiz.

**Dica: A maioria dos erros é do lado do cliente e controlável (headers, chave de API, limites de taxa), mas esse processo também ajuda você a identificar problemas que precisam de suporte WaveSpeed.