Guia 5/12
Erros
Cada erro traz um codigo estável — decida por ele, nunca pelo texto da mensagem.
| Código | HTTP | Causa | Como resolver |
|---|---|---|---|
validacao | 422 | Um ou mais campos não cumprem as regras (obrigatório, tamanho, formato, lista de valores). | Corrija os campos indicados em erro.campos e repita. |
pedido_invalido | 400 | Corpo mal formado (JSON inválido) ou parâmetros incoerentes. | Valide o JSON e o Content-Type. |
pedido_demasiado_grande | 413 | O corpo excede o limite do servidor. | Divida o pedido ou envie ficheiros por POST /ficheiros. |
nao_autenticado | 401 | Falta o cabeçalho Authorization ou o token não existe. | Peça um token novo e envie «Authorization: Bearer …». |
token_expirado | 401 | O token de acesso passou a validade. | Peça um token novo (client credentials). |
token_revogado | 401 | A clínica mudou a integração ou rodou o segredo. | Confirme as credenciais com a clínica e peça novo token. |
credenciais_invalidas | 401 | Email ou palavra-passe errados (só entradas interativas). | Não se aplica a integrações. |
codigo_invalido | 401 | Código de uso único errado ou expirado. | Peça um novo código. |
desafio_invalido | 401 | O desafio de entrada expirou. | Recomece a entrada. |
dois_fatores | 401 | Falta o segundo fator. | Complete o passo de 2FA. |
conta_bloqueada | 403 | Demasiadas tentativas falhadas. | Aguarde o tempo indicado. |
ip_nao_permitido | 403 | O endereço de origem não está nas redes autorizadas da integração. | Peça à clínica para acrescentar o seu IP. |
origem_nao_permitida | 403 | A origem do navegador não está autorizada (CORS). | Peça à clínica para acrescentar a origem ou faça o pedido no servidor. |
sem_permissao | 403 | O âmbito do token não cobre o módulo ou o nível pedido. | Peça o âmbito em falta (ex.: crm.leads:editar). |
nao_encontrado | 404 | O registo não existe, foi arquivado ou está fora do âmbito. | Confirme o id; para listas use filtros. |
ligacao_invalida | 404 | Ligação pública inexistente, expirada ou já usada. | |
metodo_nao_permitido | 405 | Método HTTP não suportado neste caminho. | Veja a referência do endpoint. |
conflito | 409 | O estado atual do registo impede a operação. | Leia o registo e confirme o estado antes de repetir. |
acao_recusada | 409 | A ação foi recusada por uma regra de negócio. | Leia erro.mensagem; não repita sem mudar os dados. |
idempotencia_conflito | 409 | A mesma Idempotency-Key foi usada com outro corpo. | Gere uma chave nova para cada operação diferente. |
idempotencia_em_curso | 409 | Um pedido com a mesma chave ainda está a ser processado. | Aguarde uns segundos e repita. |
limite_excedido | 429 | Ultrapassou o limite de pedidos por minuto. | Respeite Retry-After e use espera exponencial. |
erro_interno | 500 | Erro inesperado no servidor. | Repita mais tarde; se persistir, envie o X-Request-Id. |
Repetições
- Repita com espera exponencial só em
429,500,502,503,504e falhas de rede. - Nunca repita erros
4xxsem mudar o pedido (exceto 429 eidempotencia_em_curso). - Envie sempre
Idempotency-Keyem POST para que as repetições sejam seguras.