Formato de resposta de erro
Toda resposta de erro segue uma estrutura de envelope consistente:Tipos de erro
Códigos de erro
Erros de chave de API
As falhas do ciclo de vida da chave de API reutilizam os códigos padrão acima:- Validade inválida — um
apiKeyConfig.validForDays(na criação da conta) ou umvalidForDays(na regeneração) fora do intervalo permitido 1–365 é rejeitado comparameter_invalid(400). - Regeneração limitada por taxa — mais de uma regeneração para a mesma conta em 2 minutos retorna
rate_limit_exceeded(429). - Chave inválida ou expirada — uma chave de API revogada, desconhecida ou expirada é rejeitada na autenticação com
authentication_required(401) e a mensagem “Invalid API key.” Um cabeçalhoAuthorizationausente retorna o mesmo código com a mensagem “API key is required.” Uma chave expirada não é reportada com um código distinto — ela parece exatamente uma chave inválida, então rotacione a chave da conta pra recuperar o acesso. - Chave publicável usada diretamente — uma chave publicável (
pk_) apresentada como token Bearer em qualquer endpoint retornapermission_denied(403): “Publishable keys cannot call the API directly…”. Chaves publicáveis são somente para troca (embed de navegador); use sua chave secreta para as chamadas de API.
Gate de revisão CDSS
GET /scribe-sessions/{id} e GET /medical-record-configurations são bloqueados com
cdss_review_required (428) para uma chave de API com escopo de médico quando a instituição
dele tem o gate de revisão pendente de CDSS habilitado e o médico tem pelo menos uma sugestão
de CDSS não revisada dentro da janela configurada pela instituição (padrão de 7 dias). Chaves
com escopo institucional nunca são bloqueadas. O array error.details.pendingConsultations da
resposta lista as sessões que estão bloqueando, cada uma com uma url que aponta diretamente
para a consulta no scribe-web onde o médico aceita ou rejeita as sugestões pendentes — assim
que todas as sugestões listadas forem revisadas, a mesma requisição é concluída imediatamente
(sem cache).