> ## Documentation Index
> Fetch the complete documentation index at: https://docs.westhetics.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Um envelope só, em pt-BR, com a causa e o caminho. O código diz o que fazer; a mensagem pode ir direto para a tela.

Toda resposta de erro tem o mesmo envelope. A mensagem é escrita para uma pessoa: diz o que falhou e o que fazer, e pode ir direto para a tela do seu sistema.

```json theme={null}
{
  "error": {
    "code": "validation_failed",
    "message": "Alguns campos precisam de atenção.",
    "fields": {
      "docNumber": "Esse CPF não é válido. Confira os dois últimos dígitos.",
      "whatsapp": "O telefone precisa de DDD e número, como 64 99245-2797."
    },
    "requestId": "2730cba1-4431-4c10-a8f7-86458080df06"
  }
}
```

| Campo | O quê |
| - | - |
| `code` | o código estável, em inglês; é nele que o seu código decide |
| `message` | a frase para a pessoa, em pt-BR; pode mudar de redação |
| `fields` | só em `validation_failed`: a mensagem de cada campo; erro de regra sem campo vem em `fields._` |
| `requestId` | o mesmo do cabeçalho `x-request-id`; mande junto quando pedir ajuda |

Alguns `409` trazem dados para o seu sistema seguir sozinho. O CPF repetido, por exemplo, traz a ficha que já existe:

```json theme={null}
{
  "error": {
    "code": "conflict",
    "message": "Já existe um cadastro de Amanda Ribeiro Costa com este CPF. Abra a ficha existente em vez de criar outra.",
    "existing": {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Amanda Ribeiro Costa",
      "archivedAt": null
    },
    "requestId": "8d1f…"
  }
}
```

## Códigos

| `code` | Status | Quando | O que fazer |
| - | - | - | - |
| `bad_request` | 400 | o corpo não é JSON, ou o formato está errado | confira o `Content-Type` e o JSON |
| `unauthenticated` | 401 | sem `Authorization`, chave que não confere, chave revogada, token OAuth vencido | peça a chave nova à clínica, ou conecte de novo pelo OAuth |
| `forbidden` | 403 | o app não tem o escopo, o perfil da pessoa não pode, ou a clínica está bloqueada | a mensagem diz a permissão que falta; a gestora inclui em Integrações |
| `not_found` | 404 | o id não existe nesta clínica (inclusive o de outra clínica) | confira o id; os eventos ficam 30 dias |
| `conflict` | 409 | duplicidade ou estado que não permite a ação: CPF repetido, anamnese já aberta, já enviado | leia a mensagem; muitos trazem o id do que já existe |
| `validation_failed` | 422 | campo inválido, ou regra que só o banco confere (falta o responsável, falta o termo) | mostre `fields` ao lado de cada campo |
| `rate_limited` | 429 | passou de 100 requisições por minuto | espere o `Retry-After`; veja [limites](https://docs.westhetics.io/limites.md) |
| `internal_error` | 500 | falha nossa | tente de novo com a mesma `Idempotency-Key` e mande o `requestId` |
| `unavailable` | 503 | um serviço de que a operação depende está fora (o gerador de PDF, o provedor de mensagens) | tente de novo em alguns minutos; a mensagem diz a alternativa quando há |

> [!TIP]
>
> Decida pelo `code` e pelo status, nunca pela `message`. A mensagem melhora de redação sem aviso; o
> código não muda dentro da v1.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.