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

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.

Erros de pré-processamento de real_person

Quando o pré-processamento de imagem com real_person: true falha por causa da imagem fornecida, a API retorna HTTP 400 com error.code: "invalid_request". O fim de error.message inclui um dos motivos estáveis abaixo e identifica a referência com falha, por exemplo input_references[0]:

{
  "error": {
    "code": "invalid_request",
    "message": "real_person image processing failed — input_references[0]: ... (not_image)"
  }
}

Na lógica da aplicação, continue ramificando por error.code. Use o motivo e a posição da referência para corrigir a entrada ou diagnosticar o problema.

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": "..." } }

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.