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

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.

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