{
"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 |
409 trazem dados para o seu sistema seguir sozinho. O CPF repetido, por exemplo, traz a ficha que já existe:
{
"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 |
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á |
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.