Erros e novas tentativas | transcript1 docs

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:

Campo	Código associado	O que informa
`action_url`	`insufficient_minutes`	Link para contratar um plano ou comprar uma recarga.
`minutes_needed`, `minutes_remaining`	`insufficient_minutes`	Quantos minutos a chamada precisa consumir e quantos você tem. Se a duração ainda não for conhecida, o primeiro valor será `null`.
`supported_platforms`	`unsupported_platform`	Valores de plataforma aceitos: `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`.
`missing_chunks`	`upload_incomplete`	Índices das partes que ainda faltam no upload.
`max_bytes`	`media_too_large`	Tamanho máximo de arquivo permitido na sua conta, em bytes.
`params`	`invalid_request`	Objeto com os campos inválidos do corpo ou da query string e a explicação do problema em cada um.

Quando a API recusa a chamada

Status HTTP	`code`	Pode repetir?	O que aconteceu
400, 422	`invalid_request`	Não	Falta um parâmetro ou há um campo inválido no corpo. Isso inclui combinar `diarize` com `source: "captions"`, combinar `reuse_recent` com `webhook_url` ou enviar um JSON inválido.
422	`invalid_url`	Não	O link não foi aceito ou `platform` não corresponde ao endereço. Use YouTube, X, TikTok, Instagram, Facebook, Bluesky ou outra plataforma de Links aceitos e opções.
422	`unsupported_platform`	Não	O valor de `platform` não está entre as plataformas aceitas.
422	`unsupported_media`	Não	A extensão do arquivo enviado não está entre as aceitas.
401	`unauthorized`	Não	Falta a credencial, ou ela é inválida, expirou ou foi revogada. Também vale para token de upload inválido ou expirado.
403	`insufficient_scope`	Não	O token OAuth não tem o escopo necessário: `transcriptions:read` ou `transcriptions:write`.
403	`email_not_verified`	Não	Você precisa confirmar o e-mail antes de criar uma transcrição.
402	`insufficient_minutes`	Não	O saldo disponível é 0 ou não cobre a duração da transcrição.
402	`no_active_plan`	Não	A compra de recarga exige um plano pago ativo. Esse erro vem do endpoint de cobrança do painel, não dos endpoints de transcrição.
404	`not_found`	Não	Essa transcrição não existe ou é de outra equipe.
409	`upload_incomplete`	Não	Ainda faltam partes do arquivo. Envie o que falta e peça a conclusão do upload novamente.
409	`invalid_state`	Não	A transcrição já saiu da etapa de espera pelo upload. Não é mais possível enviar partes ou concluir o envio.
409	`idempotency_conflict`	Não	Você já usou esse `Idempotency-Key` com outros parâmetros.
413	`media_too_large`	Não	O tamanho do arquivo ultrapassa o seu limite. Confira Uploads.
413	`invalid_request`	Não	O corpo JSON ultrapassa 1 MB. Para arquivos grandes, o código é `media_too_large`.
429	`rate_limited`	Sim	Você atingiu o limite de chamadas por minuto. Aguarde o número de segundos de `Retry-After`.
429	`too_many_active_jobs`	Sim	Você atingiu o limite de transcrições em andamento ou de uploads abertos. Aguarde o número de segundos de `Retry-After`.
500	`internal_error`	Sim	Tivemos um erro interno. Aguarde um pouco e tente novamente.
503	`service_unavailable`	Sim	O transcript1 está indisponível no momento. Aguarde um pouco e tente novamente.

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, internal_error e service_unavailable. Respeite Retry-After quando vier na resposta. Sem esse cabeçalho, aumente a espera a cada tentativa.
Se for repetir POST /v1/transcriptions, 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.

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.

`error.code`	O que aconteceu	Vale tentar novamente?
`media_unavailable`	O vídeo não existe ou saiu do ar.	Não. Confira o link.
`media_private`	O vídeo é privado.	Não. Envie um post público ou um vídeo do YouTube público ou não listado.
`login_required`	A plataforma só libera o conteúdo após login.	Não. O serviço não repete essa tentativa.
`no_audio`	Não há faixa de áudio no vídeo.	Não. O serviço não repete essa tentativa.
`age_restricted`	O acesso ao vídeo tem restrição de idade.	Não pelo link. Envie o arquivo por upload.
`live_stream`	A transmissão está ao vivo ou ainda não começou.	Espere a transmissão terminar.
`no_captions`	Você escolheu `captions` em `source`, mas não há uma faixa de legendas que possa ser usada.	Troque para `source: "auto"` ou `"stt"`.
`media_too_long`	A gravação ultrapassa o limite de 5 horas do speech-to-text.	Divida a gravação antes de enviar.
`unsupported_media`	Não foi possível ler o arquivo, ou ele não tem faixa de áudio.	Envie outro arquivo em um formato aceito.
`no_speech`	Nenhuma fala detectada.	Não.
`unsupported_language`	O serviço não aceita o idioma da gravação.	Corrija `language` para um código aceito ou `"auto"`.
`insufficient_minutes`	O saldo acabou antes de cobrarmos a transcrição.	Faça uma recarga antes de tentar.
`fetch_failed`	Não conseguimos baixar o áudio ou vídeo, mesmo após várias tentativas.	Sim. Tente mais tarde.
`transcription_failed`	A transcrição por speech-to-text falhou após várias tentativas.	Sim. Tente mais tarde.

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.