Erros

Erros seguem o envelope padrão:

{
	"error": {
		"code": "validation",
		"message": "The request body failed validation; `fields` maps each invalid field to a stable message key.",
		"retryable": false,
		"requestId": "0f9c2e5a-8f4b-4d61-9a3e-2c7d1b5f0a44",
		"fields": { "url": "url_invalid" }
	}
}

• message explica em texto o que houve. É o campo para ler durante a integração e para registrar no seu log.
• code identifica o tipo do erro e é o que o seu código deve testar: sempre um dos códigos abaixo, nunca uma string arbitrária.
• retryable diz se repetir a MESMA requisição pode dar outro resultado. É a única decisão que o código HTTP não responde sozinho: um 429 se repete, um 409 de idempotência nunca vai passar. Ramifique por ele em vez de manter a sua própria tabela de quais erros valem retry.
• requestId é o identificador desta resposta, também no header X-Request-Id. Guarde-o no seu log: é por ele que encontramos, do nosso lado, o que aconteceu naquela chamada específica.
• fields (apenas em validation) aponta uma chave estável por campo inválido.

retryable: true não quer dizer "repita agora": em rate_limited o Retry-After diz quando, e nos demais vale espera exponencial com jitter.

Códigos

A referência da API documenta, por endpoint, exatamente quais códigos cada status pode devolver.

Limites de requisição

Toda resposta de uma rota limitada traz os três cabeçalhos, não só o 429:

É com eles que dá para desacelerar ANTES de bater no teto, em vez de descobri-lo sendo recusado. O 429 rate_limited traz ainda Retry-After com a espera real, em segundos. Os tetos são por conta, em janela deslizante:

Um backlog destravando de uma vez encosta nesses tetos com facilidade, porque o pico de um cliente não se parece com o tráfego médio dele. Espalhe a rajada pela espera do Retry-After em vez de tentar de novo na hora; nada é perdido, só adiado. Precisando de mais, fale com a gente antes de a migração começar.

Chaves de validação

Falhas de transcrição

Quando uma transcrição termina em status: "failed", o campo error dela traz { code, message } com o motivo. Transcrições que falham não são cobradas.

status: "canceled" não é falha: é uma transcrição que você cancelou com POST /v1/transcripts/{id}/cancel. Ela é terminal, error fica null e nada é cobrado.