Erros e novas tentativas

Uma chamada pode falhar antes de criar a transcrição: nesse caso, a API recusa a requisição. Também pode aceitar a transcrição e encontrar um problema depois, durante o processamento. Nesse segundo caso, o objeto da transcrição fica com status igual a failed.

Como ler a resposta de erro

Quando uma chamada a /v1 falha, você recebe o erro neste formato:

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

No código da sua aplicação, use code para decidir o que fazer. O campo message serve para exibir uma explicação ao usuário e pode mudar de texto. Se retryable for true, vale repetir a mesma chamada mais tarde.

Dependendo do erro, a resposta inclui outros campos junto de retryable:

Quando a API recusa a chamada

Quando o navegador usa o cookie de login em vez de uma credencial Bearer, também conferimos a origem da chamada. Se ela vier de outro site, a resposta será 403 forbidden_origin. Essa verificação não afeta chamadas à API com o cabeçalho Authorization.

Toda resposta 429 informa em Retry-After quantos segundos você deve esperar. Os valores de cada plano estão em Planos, minutos e limites.

Quando e como tentar novamente

• Repita a chamada apenas se retryable for true. Isso vale para rate_limited, too_many_active_jobs, too_many_live_sessions, live_capacity, internal_error, service_unavailable e para topup_needs_user com reason pending ou in_progress. Respeite Retry-After quando vier na resposta. Sem esse cabeçalho, aumente a espera a cada tentativa.
• Se for repetir POST /v1/transcriptions ou POST /v1/topups, mantenha o mesmo Idempotency-Key. Assim você evita outra cobrança caso a primeira chamada tenha funcionado.
• Nos demais erros, corrija a causa antes de enviar a chamada novamente.

Transcrição ao vivo

POST /v1/live/sessions e os demais endpoints ao vivo usam o mesmo formato de erro. invalid_request, unsupported_language, insufficient_minutes e email_not_verified também valem para eles, junto com os códigos ao vivo da tabela acima. Criar uma sessão não é idempotente: repetir a chamada após too_many_live_sessions ou live_capacity cria uma sessão nova.

Depois que a sessão existe, os problemas chegam pelo WebSocket como eventos error e códigos de fechamento, não como erros HTTP. Veja todos os eventos em Transcrição ao vivo.

Uma sessão ao vivo que termina por um motivo como balance_exhausted ou idle_timeout não é um erro: ela envia session.ended com o motivo do encerramento e é salva. Veja Motivos de encerramento.

Falhas durante a transcrição

Se o processamento falhar, o objeto fica com status igual a failed e inclui error: { "code", "message" }. Isso pode acontecer depois da resposta à chamada de criação. Leia error nas consultas de status ou no webhook transcription.failed. Se uma tradução falhar, o webhook transcription.translation.failed é enviado e a transcrição nunca falha por causa disso.

Se a transcrição falhar ou você cancelar, não paga por ela. Se já tivermos descontado os minutos, eles voltam para o seu saldo.