# Erros e novas tentativas

> Entenda os códigos da API, diferencie erros de chamada de falhas na transcrição e saiba quando tentar novamente.

Canonical: https://transcript1.com/pt/docs/errors
Language: pt-BR
Last updated: 2026-10-19

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:

```json
{
  "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](https://transcript1.com/pt/docs/sources-and-options). |
| 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](https://transcript1.com/pt/docs/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](https://transcript1.com/pt/docs/billing-and-limits).

## 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](https://transcript1.com/pt/docs/webhooks) `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.