Erros

Os erros usam um envelope só, em toda a API:

{
  "error": {
    "type": "ForbiddenError",
    "title": "Forbidden",
    "detail": "The transcriptions.read scope is required.",
    "code": "INSUFFICIENT_SCOPE",
    "request_id": "req_9bfbe80ac1f24e0a9d5b1e5e7a0f2c11"
  }
}

Ramifique pelo code

O code é o campo estável, legível por máquina. Ele não muda com redação, tradução ou refatoração.

title e detail são texto humano e podem ser reescritos entre versões. O type é a classe do erro e é estável, mas mais grosseiro que o code — vários códigos compartilham uma classe. Nunca faça parse do detail.

Cite o request_id ao acionar o suporte: ele identifica a requisição exata no nosso log.

Códigos

HTTP	code	Significado
400	INVALID_LIMIT	Tamanho de página fora de 1–100.
400	INVALID_DATETIME	Um carimbo de tempo não é RFC 3339 com offset explícito.
400	INVALID_FILTER	Valor ou combinação de filtro não suportada.
400	INVALID_CURSOR	O cursor foi editado, ou os filtros mudaram no meio da travessia.
400	INVALID_REQUEST	Falha de validação, incluindo parâmetro de query desconhecido.
401	MISSING_ACCESS_TOKEN	Nenhum bearer token foi enviado.
401	INVALID_ACCESS_TOKEN	O token é inválido, expirou, ou a credencial foi revogada.
403	INSUFFICIENT_SCOPE	O token não carrega o escopo que a rota exige.
403	API_ACCESS_DISABLED	A empresa não tem acesso à API habilitado.
404	RESOURCE_NOT_FOUND	Não existe, é de outra empresa, ou foi pedido na coleção errada.
413	PAYLOAD_TOO_LARGE	O corpo da requisição excede o tamanho aceito.
415	UNSUPPORTED_MEDIA_TYPE	Content type errado — em geral JSON enviado ao /oauth/token.
429	RATE_LIMIT_EXCEEDED	Uma política de rate limit recusou a requisição.
503	SERVICE_UNAVAILABLE	Dependência fail-closed indisponível. Repita com backoff.
503	AUDIT_UNAVAILABLE	Uma leitura bem-sucedida não pôde ser gravada na trilha de auditoria, então não foi devolvida.

Identificador desconhecido é sempre 404

Um id de outra empresa devolve 404 RESOURCE_NOT_FOUND, não 403. A API não confirma que o recurso existe em outro lugar — um 403 entregaria esse fato a quem estivesse sondando ids.

O endpoint de token é diferente

POST /oauth/token devolve o formato de erro do OAuth 2.0 exigido pela RFC 6749 §5.2, para que clientes OAuth de mercado continuem funcionando:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

O que nunca aparece num erro

Stack trace, caminho de arquivo, token, secret, corpo da requisição e payload de domínio nunca são devolvidos. Uma falha inesperada devolve mensagem genérica fixa com um request_id; o detalhe fica no nosso log.

Quando repetir

Status	Repetir?
400, 403, 404, 413, 415	Não. A requisição vai falhar igual.
401	Uma vez, depois de reemitir o token.
429	Sim, depois do Retry-After.
503	Sim, com backoff exponencial e jitter.