Guide 5/12
Errors
Every error carries a stable codigo — branch on it, never on the message text.
| Code | HTTP | Cause | How to fix |
|---|---|---|---|
validacao | 422 | One or more fields break the rules (required, length, format, allowed values). | Fix the fields listed in erro.campos and retry. |
pedido_invalido | 400 | Malformed body (invalid JSON) or inconsistent parameters. | Validate the JSON and the Content-Type. |
pedido_demasiado_grande | 413 | The body exceeds the server limit. | Split the request or upload files through POST /ficheiros. |
nao_autenticado | 401 | Missing Authorization header or unknown token. | Request a new token and send «Authorization: Bearer …». |
token_expirado | 401 | The access token expired. | Request a new token (client credentials). |
token_revogado | 401 | The clinic changed the integration or rotated the secret. | Confirm the credentials with the clinic and request a new token. |
credenciais_invalidas | 401 | Wrong email or password (interactive sign-in only). | Does not apply to integrations. |
codigo_invalido | 401 | Wrong or expired one-time code. | Request a new code. |
desafio_invalido | 401 | The sign-in challenge expired. | Start the sign-in again. |
dois_fatores | 401 | Second factor required. | Complete the 2FA step. |
conta_bloqueada | 403 | Too many failed attempts. | Wait for the indicated time. |
ip_nao_permitido | 403 | The source address is not in the integration allowed networks. | Ask the clinic to add your IP. |
origem_nao_permitida | 403 | The browser origin is not allowed (CORS). | Ask the clinic to add the origin or call from your server. |
sem_permissao | 403 | The token scope does not cover the module or level. | Request the missing scope (e.g. crm.leads:editar). |
nao_encontrado | 404 | The record does not exist, was archived or is out of scope. | Check the id; use filters on lists. |
ligacao_invalida | 404 | Public link not found, expired or already used. | |
metodo_nao_permitido | 405 | HTTP method not supported on this path. | Check the endpoint reference. |
conflito | 409 | The record current state prevents the operation. | Read the record and check its state before retrying. |
acao_recusada | 409 | A business rule refused the action. | Read erro.mensagem; do not retry without changing data. |
idempotencia_conflito | 409 | The same Idempotency-Key was used with a different body. | Generate a new key for each different operation. |
idempotencia_em_curso | 409 | A request with the same key is still running. | Wait a few seconds and retry. |
limite_excedido | 429 | You exceeded the per-minute limit. | Honour Retry-After and back off exponentially. |
erro_interno | 500 | Unexpected server error. | Retry later; if it persists, send the X-Request-Id. |
Retries
- Retry with exponential back-off only on
429,500,502,503,504and network failures. - Never retry
4xxerrors unchanged (except 429 andidempotencia_em_curso). - Always send an
Idempotency-Keyon POST so retries are safe.