Início → Blog → Erros da API de transcrição e o que eles realmente significam

Erros da API de transcrição e o que eles realmente significam

Integrações quebram pouco e sempre na hora errada. A boa notícia: os erros de transcrição vêm de uma lista curta de causas e a maioria se resolve em um minuto. Vamos por ordem, indicando também quais merecem retentativa automática.

Tabela de códigos

O corpo do erro segue o formato conhecido — um objeto error com message e type — de modo que exceções tipadas dos SDKs continuam funcionando.

401 quase sempre é o cabeçalho

Três causas típicas, por frequência:

• A chave carrega um espaço ou quebra de linha, sobretudo quando copiada de um e-mail.
• Falta a palavra Bearer: o cabeçalho precisa ser Authorization: Bearer sua_chave.
• Chave de homologação foi parar em produção, ou o contrário.

A checagem mais rápida é um curl — se passar, o problema está no código, não no acesso.

429 significa duas coisas

O mesmo código chega quando você envia rápido demais e quando os minutos pagos acabaram. O texto da mensagem distingue os casos. O primeiro se resolve com fila e limite de paralelismo; o segundo, recarregando o saldo.

Bom hábito: acompanhar o saldo na área do cliente e configurar aviso com antecedência, em vez de descobrir pelo log de produção.

Como repetir direito

Só falhas temporárias merecem repetição: 429, 502 e quedas de rede. 400, 401 e 413 devolverão exatamente a mesma resposta para sempre — isso se corrige, não se martela.

import time
from openai import OpenAI, APIStatusError, APIConnectionError

client = OpenAI(base_url="https://voicesscribe.com/v1", api_key="sua chave", max_retries=0)

def transcribe(path, tries=4):
    delay = 2
    for attempt in range(tries):
        try:
            with open(path, "rb") as f:
                return client.audio.transcriptions.create(model="whisper-1", file=f).text
        except APIStatusError as e:
            if e.status_code not in (429, 500, 502, 503):
                raise
        except APIConnectionError:
            pass
        time.sleep(delay)
        delay *= 2
    raise RuntimeError("não foi possível transcrever " + str(path))

Dobrar a espera importa mais que o número de tentativas: dá folga ao serviço e evita que você esbarre no mesmo limite um segundo depois.

Perguntas frequentes

Leitura relacionada

• Voz para texto em Python: de um arquivo a um script que funciona — Transcrição em Python funcionando em dez minutos: instalação, a primeira requisição, formatos de resposta, tratamento de erros e os erros que mais custam tempo.
• Como transcrever uma gravação que não cabe em uma requisição — O que fazer com áudio de várias horas: compressão, corte nas pausas, processamento paralelo dos pedaços e junção em um texto com tempos contínuos.
• Como montar um pipeline de transcrição para um acervo de áudio — Transcrever milhares de gravações sem perder nenhuma: fila de trabalho, concorrência, novas tentativas, retomada após uma queda e controle do valor da fatura.