> ## Documentation Index > Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Tratamento de erros > Códigos de status HTTP e formato de resposta de erro ## Formato de resposta de erro Toda resposta de erro segue uma estrutura de envelope consistente: ```json theme={null} { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "idCountry must be a valid country name, ISO alpha-2, or ISO alpha-3 code.", "param": "idCountry" } } ``` | Campo | Tipo | Descrição | | --------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Categoria geral do erro para tratamento de alto nível. | | `code` | string | Código de erro legível por máquina. Os clientes devem fazer switch sobre esse valor. | | `message` | string | Mensagem de erro legível por humanos que termina com ponto. | | `param` | string ou null | O campo da requisição que causou o erro, se aplicável. | | `details` | object ou null | Contexto estruturado e legível por máquina, opcional, para o erro. Presente somente em códigos de erro que precisam dele (ex.: `cdss_review_required`). | ## Tipos de erro | Tipo | Descrição | | ----------------------- | ------------------------------------------------------------ | | `invalid_request_error` | A requisição está malformada ou contém parâmetros inválidos. | | `authentication_error` | A autenticação falhou (chave de API ausente ou inválida). | | `permission_error` | A chave de API não tem permissão pra essa operação. | | `api_error` | Ocorreu um erro interno ou de um serviço upstream. | ## Códigos de erro | Código | Status HTTP | Descrição | | ------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- | | `parameter_missing` | 400 | Um campo obrigatório está ausente no body da requisição. | | `parameter_invalid` | 400 | O valor de um campo está malformado ou não é aceito. | | `account_invalid` | 400 | A conta associada à chave de API está mal configurada. | | `authentication_required` | 401 | Chave de API ausente ou inválida. | | `permission_denied` | 403 | Permissões insuficientes pra essa operação. | | `resource_not_found` | 404 | O recurso solicitado não existe. | | `resource_conflict` | 409 | Já existe um recurso com o identificador fornecido. | | `cdss_review_required` | 428 | O médico tem sugestões de CDSS pendentes de revisão; veja [Gate de revisão CDSS](#gate-de-revisão-cdss). | | `rate_limit_exceeded` | 429 | Muitas requisições em um curto período; tente novamente após uma breve espera. | | `service_unavailable` | 503 | Uma dependência externa está temporariamente fora do ar. | ## 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](/pt-BR/scribe-api/accounts#regenerar-uma-chave-de-api)) 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](/pt-BR/scribe-api/accounts#regenerar-uma-chave-de-api) 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](/pt-BR/scribe-api/authentication#tipos-de-chave) (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 ```json theme={null} { "error": { "type": "invalid_request_error", "code": "parameter_missing", "message": "name is required.", "param": "name" } } ``` ### Chave de API inválida ```json theme={null} { "error": { "type": "authentication_error", "code": "authentication_required", "message": "Invalid API key." } } ``` ### Recurso não encontrado ```json theme={null} { "error": { "type": "invalid_request_error", "code": "resource_not_found", "message": "No session scribe found for the given consultation ID." } } ``` ### Conflito de ID de consulta ```json theme={null} { "error": { "type": "invalid_request_error", "code": "resource_conflict", "message": "consultationInternalId is already in use by a different consultation.", "param": "consultationInternalId" } } ``` ### Revisão de CDSS necessária ```json theme={null} { "error": { "type": "invalid_request_error", "code": "cdss_review_required", "message": "This doctor has 1 pending CDSS suggestion awaiting review from the last 7 days. The API is blocked by your institution until the suggestions are reviewed. Open the consultation(s) to accept or reject them: https://scribe.telepatia.ai/consultations/session-abc-123.", "details": { "pendingConsultations": [ { "sessionId": "session-abc-123", "url": "https://scribe.telepatia.ai/consultations/session-abc-123" } ] } } } ``` ### Limite de requisições excedido ```json theme={null} { "error": { "type": "invalid_request_error", "code": "rate_limit_exceeded", "message": "Too many API key regenerations. Try again in a couple of minutes." } } ```