Erros

O Reigniter API usa códigos de status HTTP padrão. Cada resposta de erro é JSON.

Corpo de erro

A maioria dos erros se apresenta assim:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 37
}

Campo	Sempre presente	O que é
`error`	Sim	Uma mensagem que você pode mostrar para uma pessoa. Pode mudar a redação, então não faça correspondência.
`code`	Mais erros	Um código estável, em maiúsculas. Desvie sobre isso.
`details`	Alguns erros	Contexto extra, por exemplo, `retryAfter` ou números de uso.
`retryAfter`	Alguns `429`s	Segundos para esperar antes de tentar novamente.

Alguns erros não têm code, como 404 Job not found e 403 Forbidden. Branch no status para esses.

Erros de validação

Quando o corpo da requisição não corresponde ao esquema, você recebe 400 com uma string de detail que lista cada problema como field: message:

{
  "error": "Validation failed",
  "detail": "aspect: Invalid option: expected one of \"9:16\"|\"16:9\"|\"1:1\"|\"4:5\"|\"4:3\"|\"3:4\""
}

Códigos de status

Status	Significado	O que fazer
`200`	Sucesso.
`201`	Criados (webhooks).
`202`	Aceito. A renderização começou.	Consulte o trabalho ou espere pelo webhook.
`400`	O pedido foi recusado. Nada foi acusado.	Corrija o pedido. Não tente novamente sem alterações.
`401`	Chave faltante, inválida ou revogada API.	Confira a chave.
`402`	Problema de planejamento, crédito ou uso.	Leia `code`.
`403`	Conta suspensa, ou um emprego que não é seu.	Entre em contato com o suporte ou verifique o ID do emprego.
`404`	Não encontrado.	Verifique o ID ou o caminho.
`409`	Solicitação duplicada ou limite atingido.	Leia `code`.
`413`	Essa renderização custaria mais do que o limite por render.	Use menos cenas ou um `quality` menor.
`422`	O render não tem marca, produto ou apresentador para ancorá-lo.	Veja vídeos de fabricação.
`429`	Pedidos demais ou renderizações demais ao mesmo tempo.	Espere e tente novamente. Veja Limites.
`500`	Algo deu errado do nosso lado.	Tente depois.
`502`	O planejamento do seu briefing falhou. Créditos de planejamento foram reembolsados.	Retenta, ou reformule o resumo.
`503`	A renderização é pausada ou um serviço está fora do ar. Nada foi cobrado.	Tente depois.

Um caminho desconhecido sob /v1/ retorna 404 com code: "NOT_FOUND".

Códigos de erro

Autenticação e plano

Código	Status	Significado
`NO_API_KEY`	401	Sem cabeçalho `Authorization`, ou o token não começa com `emp_`.
`INVALID_API_KEY`	401	A chave é desconhecida ou revogada.
`PLAN_UPGRADE_REQUIRED`	402	API acesso precisa do plano Agency.
`ACCOUNT_SUSPENDED`	403	A conta está suspensa.

Créditos e uso

Código	Status	Significado
`NO_CREDITS`	402	A conta não tem mais créditos.
`INSUFFICIENT_CREDITS`	402	Não há créditos suficientes para esse render.
`ABUSE_CAP_EXCEEDED`	402	O limite mensal de uso do plano é atingido.
`STORAGE_FULL`	402	A biblioteca de vídeos da conta está cheia. Remova alguns vídeos.
`UPGRADE_REQUIRED`	402	Vídeo precisa de um plano pago.
`REQUEST_COST_TOO_HIGH`	413	Essa renderização custaria mais do que o limite por render.

Veja Conta e faturamento para créditos e planos.

Solicitações de renderização

Código	Status	Significado
`CONTENT_BLOCKED`	400	O briefing ou uma cena quebra as regras de conteúdo.
`PRODUCT_IMAGE_REQUIRED`	400	Esse formato precisa de `product_image_url`, ou `product_enabled: false`.
`PRESENTER_REQUIRED`	400	Uma cena de conversa não tem rosto. Adicione `avatar_preset_id`, ou envie `presenter_enabled: false`.
`UNSUPPORTED_MODEL`	400	Uma cena pediu um modelo de renderização Reigniter não pode usar.
`BRAND_REQUIRED`	422	Pediram uma marca, mas nenhuma foi encontrada. Envie `brand_logo_url`.
`NO_ANCHOR`	422	Sem marca, foto do produto ou apresentador. Adicione um, ou faça a opção de não participar.
`CANVAS_NOT_FOUND`	404	Um projeto referenciado não está nessa conta.
`DUPLICATE_REQUEST`	409	Essa `Idempotency-Key` já estava usada. Nada novo foi carregado.
`PLAN_FAILED`	502	O planejamento do resumo falhou. Créditos de planejamento foram reembolsados.

Com um brief, um Idempotency-Key repetido também pode voltar como 402 com a mensagem This request was already submitted. Trate como uma duplicação, não como um problema de crédito.

Taxa e concorrência

Código	Status	Significado
`RATE_LIMITED`	429	Pedidos demais. Espere `retryAfter` (ou `details.retryAfter`) segundos.
`CONCURRENT_LIMIT`	429	Muitos renders rodando ao mesmo tempo. Espere um terminar.

Serviço

Código	Status	Significado
`USAGE_CHECK_UNAVAILABLE`	503	O uso não pôde ser verificado, então a renderização foi pausada. Nada foi cobrado.
`DB_UNAVAILABLE`	503	Um serviço fica temporariamente indisponível.
`FEATURE_NOT_AVAILABLE`	503	Renderização não está disponível no momento.
`GLOBAL_KILL_SWITCH`	503	A renderização é pausada para todos.
`FEATURE_KILL_SWITCH`	503	Este recurso está pausado.
`USER_KILL_SWITCH`	503	Esta conta está temporariamente restrita. Entre em contato com o suporte.

Webhooks

Código	Status	Significado
`UNKNOWN_EVENT`	400	Não é um evento para o qual você pode se inscrever. A resposta lista os válidos.
`URL_NOT_DELIVERABLE`	400	A URL não é um endereço http público(s).
`HOOK_LIMIT`	409	A conta já possui o número máximo de webhooks.

Retentando com segurança

Retente 429, 500, 502 e 503 com backoff. Não tente outras 4xx sem alterações.
Sempre envie um Idempotency-Key sobre POST /v1/render.
Nenhuma resposta (um timeout ou uma conexão caída): tente novamente com a mesma chave. Se a primeira solicitação iniciou uma renderização, a retentativa é recusada em vez de iniciar uma segunda.
Resposta de erro: nenhuma renderização foi iniciada para essa solicitação. Corrija a causa e tente novamente com uma nova chave, porque uma solicitação que falhou parcialmente pode já ter usado sua chave. Créditos de renderização são reembolsados. A única cobrança que não é reembolsada é o planejamento breve, quando a renderização planejada é então recusada (veja Criar vídeos).
Se uma renderização foi aceita (202) e depois falhar, a status do trabalho se torna failed e error explica o motivo. Créditos por trabalhos que não aconteceram são reembolsados.