Erros

English · Português (Brasil)

Toda exceção que o SDK lança pode ser importada de diagnos, e cada uma nomeia uma decisão que você precisa tomar: corrigir a entrada, esperar, refazer o enrollment, pedir a um admin, ou reportar um bug. Capture por classe, nunca por mensagem — mensagens são para pessoas e podem mudar; classes e codes são o contrato. A CLI e a API REST traduzem as mesmas classes em códigos de saída e status HTTP, então esta página é a tabela única para os três.

A hierarquia#

classDiagram
    DiagnosError <|-- ConfigError
    DiagnosError <|-- EnrollmentDeniedError
    DiagnosError <|-- EnrollmentExpiredError
    DiagnosError <|-- SessionExpiredError
    DiagnosError <|-- GroupKeyUnavailable
    DiagnosError <|-- CryptoError
    DiagnosError <|-- ProtocolError
    DiagnosError <|-- VaultError
    VaultError <|-- ValidationError
    VaultError <|-- AuthenticationError
    VaultError <|-- QuotaError
    VaultError <|-- DiagnosPermissionError
    VaultError <|-- NotFoundError
    VaultError <|-- ConflictError
    VaultError <|-- RateLimitError

VaultError e as subclasses significam o cofre respondeu com um erro; carregam o code do cofre, o status HTTP, e o trace_id e o request_id de que um chamado de suporte precisa. Todo o resto sob DiagnosError é decidido localmente, antes ou depois de falar com o cofre.

Toda exceção#

Qual code do cofre vira qual classe — DocumentVersionMismatch, QuotaExceeded, ServiceAccountRevoked e o resto — é normativo, e mora no PROTOCOL.pt-BR.md §12.

Três falhas não são DiagnosErrors, porque são erros de programação pegos antes de qualquer coisa ser enviada:

MemoryLockWarning é um aviso, não um erro: o SO recusou travar uma chave na RAM, e o processo segue com toda outra proteção. DIAGNOS_MEMORY_LOCK=require o transforma numa falha dura — veja Configuração.

O que o SDK já retenta#

Antes de envolver uma chamada num laço de retentativa: o SDK já retenta tudo que é seguro retentar, com uma assinatura nova a cada vez, e só lança quando retentar deixou de fazer sentido.

O que sobra para você: ConflictError com DocumentVersionMismatch significa alguém salvou no meio-tempo — leia de novo, combine, grave de novo (exemplo). ConflictError com UploadIncomplete significa que os bytes de um arquivo nunca chegaram ao armazenamento — suba aquele arquivo de novo. RateLimitError e VaultError valem mais uma tentativa depois de uma pausa maior.

Diferença de relógio#

Toda requisição assinada carrega um horário que o cofre só aceita dentro de ±120 segundos do próprio relógio. Um notebook com relógio errado ou um container sem NTP assinaria toda requisição rumo a uma recusa, então o SDK mede a diferença contra o cofre antes da primeira chamada assinada e a aplica a toda assinatura, e ressincroniza uma vez se o cofre ainda reclamar. Você não configura nada disso.

Lendo um erro#

from diagnos import Diagnos, NotFoundError, VaultError

vault = Diagnos()
try:
    vault.patients.get("pat_nao_existe")
except NotFoundError as error:
    print(error.code, error.status)  # DocumentNotFound 404
except VaultError as error:
    print("erro do cofre", error.code, error.status, error.trace_id, error.request_id)

Logue code, status, trace_id e request_id — nunca o registro que você estava gravando. O trace_id é o que o suporte do diagnos precisa para achar o evento do lado do cofre.

Na CLI e na API REST#

A CLI imprime em stderr um rótulo bilíngue de uma linha e a mensagem, e sai com o código da tabela acima — 0 no sucesso. Decida pelo código de saída em scripts; nunca faça grep no texto:

diagnos --quiet patients get "$PATIENT_ID" > patient.txt
case $? in
  0) echo "ok" ;;
  3) echo "refaça o enrollment, ou peça acesso a um admin" ;;
  4) echo "paciente inexistente" ;;
  *) echo "falhou" ;;
esac

A API REST responde todo não-2xx com um envelope só, cujo code é o do próprio cofre quando a falha veio do cofre:

{ "error": { "code": "DocumentNotFound", "message": "…", "trace_id": "…" } }

Além dos status da tabela, ela responde 422 (invalid_request) para um corpo ou query que falha na validação, 401 (client_certificate_required) e 403 (client_certificate_cn_not_allowed) para falhas de TLS mútuo, e 404/405 para rota ou método desconhecidos — sempre no mesmo envelope. A referência da API os documenta por rota.