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 — ou, na credencial de usuário, o dono não é mais membro ativo.
403	INSUFFICIENT_SCOPE	O token não carrega o escopo que a rota exige, ou o dono de uma credencial de usuário perdeu o acesso a e-mail ou WhatsApp.
403	API_ACCESS_DISABLED	A empresa não tem acesso à API habilitado.
403	AI_COLLABORATORS_DISABLED	Conexão de um app da própria Salesbud, como os Colaboradores IA, numa empresa sem essa feature. Devolvido pelo /oauth/token e pela aprovação na tela de consentimento.
403	API_CLIENT_PENDING_APPROVAL	O token é de uma conexão feita com login OAuth que um administrador ainda não aprovou. Não adianta repetir até a aprovação. O detalhe diz “The API client is waiting for administrator approval.”.
404	RESOURCE_NOT_FOUND	Inexistente, de outra empresa, fora da visão de uma credencial de usuário, ou 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."
}

Além de invalid_request, invalid_client, invalid_scope e unsupported_grant_type, os grants das conexões OAuth respondem invalid_grant quando um code ou um refresh token expirou, já foi usado, não confere com o verificador PKCE, aponta um resource diferente do da autorização ou não tem mais uma conexão ativa nem um dono ativo por trás. Conecte de novo.

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. Nas conexões OAuth, renove com o refresh token; se falhar, reconecte.
429	Sim, depois do Retry-After.
503	Sim, com backoff exponencial e jitter.