Erros
Todo erro dos endpoints da Video API usa o mesmo formato JSON:
{
"error": {
"code": "...",
"message": "..."
}
}O status HTTP indica a classe do problema; error.code é uma string estável que você pode usar em ramificações no código. Sempre compare por error.code em vez de fazer parse de error.message.
Códigos de erro
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_request | Um parâmetro obrigatório está ausente ou um valor é inválido |
| 400 | invalid_callback_url | callback_url não usa HTTPS ou aponta para uma rede privada (bloqueada por verificações SSRF) |
| 400 | references_conflict | frame_images e input_references foram enviados na mesma requisição (mutuamente exclusivos) |
| 400 | too_many_references | input_references excede os limites (imagens > 9 / áudio > 3 / vídeo > 1) |
| 400 | cancel_not_supported | O provedor upstream não consegue interromper esta tarefa |
| 400 | cancel_failed | A tarefa já está em um estado terminal e não pode ser cancelada |
| 401 | unauthorized / invalid_api_key | A autenticação falhou |
| 401 | upstream_auth_failed | A autenticação do provedor upstream falhou |
| 402 | insufficient_credits | Saldo insuficiente para aceitar a tarefa |
| 404 | not_found | A tarefa não existe ou você não tem acesso a ela |
| 404 | model_not_found | O modelo solicitado não existe |
| 429 | rate_limited | Requisições demais (limite de taxa de polling ou limite de taxa do upstream) |
| 502 | upstream_error / route_error | Erro do provedor upstream / falha de roteamento |
| 500 | internal_error | Erro interno inesperado |
references_conflict e too_many_references são erros de validação do corpo da requisição — veja Criar vídeo para os limites exatos. cancel_not_supported e cancel_failed são descritos em Cancelar vídeo. not_found é retornado tanto para uma tarefa desconhecida quanto para uma tarefa pertencente a outra API key; os dois casos são intencionalmente indistinguíveis.
402 Créditos insuficientes
insufficient_credits é retornado apenas ao criar uma tarefa (POST /v1/videos). Quando a pré-autorização está ativada, a ofox estima o custo com base na resolução e duração solicitadas antes de aceitar a tarefa. Se a estimativa exceder seu saldo, a requisição é rejeitada imediatamente — nenhum registro de tarefa é criado e nada é cobrado.
{ "error": { "code": "insufficient_credits", "message": "..." } }insufficient_credits é o único código 402 retornado pela Video API. Trate esse único código, adicione saldo e tente novamente.
429 Limite de taxa
rate_limited cobre tanto o limite de polling por key em GET /v1/videos/{id} quanto limites de taxa do upstream. Quando você atinge o limite de polling, a resposta carrega um header Retry-After:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "..." } }Respeite o header Retry-After e aguarde antes de tentar novamente. Se você faz polling com frequência, mude para notificações de webhook para que a ofox envie o estado terminal a você — isso evita completamente o limite de polling. Criação de tarefas (POST) e cancelamento (DELETE) não são afetados pelo limite de polling.