Skip to main content

Formato de resposta de erro

Toda resposta de erro segue uma estrutura de envelope consistente:

Tipos de erro

Códigos de erro

Ids de requisição

Toda resposta de erro carrega um requestId, e toda resposta (com erro ou não) carrega o mesmo valor no cabeçalho X-Request-ID. Cite-o ao reportar um problema: ele identifica a requisição exata nos nossos logs. Se você enviar seu próprio cabeçalho X-Request-ID, nós o propagamos em vez de gerar um, então seu id de trace e o nosso coincidem. Dentro de uma resposta de criação de contas em lote o objeto error de cada item não tem requestId. Essa chamada retorna HTTP 200 e tem um único id pro lote inteiro: leia-o do cabeçalho X-Request-ID.

Falhas de autenticação x indisponibilidade da autenticação

Duas situações diferentes pareciam idênticas. Não parecem mais:
  • authentication_required (401) significa que a chave foi rejeitada. Verifique a chave ou rotacione-a. Tentar de novo não ajuda.
  • service_unavailable (503) em um endpoint autenticado significa que não conseguimos alcançar o serviço de autenticação. Sua chave está correta. Tente de novo com backoff.
  • rate_limit_exceeded (429) significa tentativas de autenticação demais em pouco tempo.

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 um validForDays (na regeneração) fora do intervalo permitido 1–365 é rejeitado com parameter_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çalho Authorization ausente 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 retorna permission_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.
  • Criar contas exige uma chave institucional — uma chave com escopo de médico chamando criação de contas é rejeitada com permission_denied (403), não com service_unavailable. Use a chave da instituição. Veja o exemplo abaixo.

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).

Exemplos

Campo obrigatório ausente

Chave de API inválida

Recurso não encontrado

Conflito de ID de consulta

Revisão de CDSS necessária

Limite de requisições excedido

Permissão negada ao criar uma conta