Solução de problemas

Encontre o sintoma e tente a correção. Se nada aqui ajudar, fale com o suporte informando o request_id.

A primeira chamada falha

401 "Missing credentials". O cabeçalho Authorization não chegou. Confira se a variável de ambiente está definida no shell ou processo que faz a requisição (echo ${POPNOW_API_KEY:0:10} deve mostrar sk-popnow-) e se algum proxy ou biblioteca HTTP está descartando o cabeçalho.

401 "Key format is not recognized". O valor não é uma chave PopNow — muitas vezes é outra coisa que estava na área de transferência. As chaves começam com sk-popnow-.

401 "Credentials are invalid or expired". A chave foi revogada, expirou ou foi digitada errado. Crie uma nova no console da API.

40310. O e-mail da sua conta não foi verificado. Abra o link do e-mail de cadastro; a chave passa a funcionar na hora.

40201 "Insufficient balance". A conta não tem créditos suficientes para a reserva desta tarefa. Reservas de vídeo podem ser grandes; confira o preço com o jobs/quote e compre créditos.

A requisição é recusada

400 citando um campo. O input não bate com o schema do modelo: um campo escrito errado, um valor fora da lista permitida ou um campo obrigatório faltando. Abra a página de referência do modelo a partir de Modelos e compare.

400 "Invalid callback URL". O callBackUrl precisa ser HTTPS público, na porta 443, sem usuário nem senha. localhost e endereços privados são recusados.

40004. O modelo funciona, mas não consegue atender essa combinação de configurações agora. Mude a configuração citada no msg (geralmente resolução, duração ou proporção).

50301. O modelo está temporariamente sem aceitar tarefas. Tente mais tarde ou escolha outro modelo.

413. O corpo JSON passou de 2 MiB, geralmente por causa de imagens embutidas. Faça upload delas.

A tarefa falha

invalid_asset. Um arquivo de referência não pôde ser baixado ou lido. Abra a URL numa janela anônima do navegador: ela precisa baixar o próprio arquivo, sem login. Páginas de compartilhamento de nuvem não funcionam.

content_rejected. O modelo recusou o prompt ou uma imagem de referência. Reescreva, use outras referências ou tente outro modelo.

timeout ou expired. O trabalho demorou mais que o permitido. Tente uma duração menor ou uma resolução mais baixa.

generation_failed. O modelo rodou, mas não gerou nada. A mesma entrada costuma falhar de novo; mude o prompt ou as configurações.

Tarefas que falham ou expiram não gastam créditos.

O resultado

O link de download retorna 403 ou "expired". Links assinados valem por uns 20 minutos. Leia a tarefa de novo com recordInfo para pegar um link novo.

O link de download falha quando envio minha chave de API. Não envie Authorization para o link assinado; o próprio link é a permissão.

recordInfo retorna 404 para uma tarefa que eu criei. As tarefas só aparecem para a chave que as criou. Use a mesma chave ou procure a tarefa no console da API.

Webhooks

Nada chega. Confira se a URL é acessível pela internet via HTTPS, se o firewall permite e se o handler responde 2xx em até 15 segundos. Entregas que falharam aparecem no console da API.

A assinatura nunca bate. Faça o hash dos bytes brutos do corpo, não de um JSON reserializado; use data.taskId, o cabeçalho X-Webhook-Timestamp e o segredo gerado mais recentemente.

A mesma tarefa chega duas vezes. É o esperado depois de uma nova tentativa. Ignore duplicatas pelo request_id.

Uploads

O PUT retorna 403 do armazenamento. Algum cabeçalho difere do ticket. Envie Content-Type e Content-Length exatamente como vieram e sem cabeçalho Authorization.

A confirmação retorna 40003. O arquivo enviado não confere com o que você declarou. Peça um ticket novo com o contentType e os bytes corretos.

A confirmação retorna 409. O ticket expirou (depois de uns 20 minutos). Peça um logo antes do upload.