Erros e limites
Trate respostas HTTP de forma previsível e respeite as orientações retornadas pela API.
Códigos de status
Cada endpoint lista suas respostas declaradas. Use o status HTTP para orientar a integração.
| Status | Como tratar |
|---|---|
2xx |
Operação aceita; leia o corpo apenas quando houver conteúdo |
400 |
Revise os parâmetros, filtros e campos enviados |
401 |
Verifique a chave e sua validade |
403 |
Verifique a permissão para o recurso |
404 |
Confira o identificador e o contexto do escritório |
409 |
Resolva o conflito com o estado atual do recurso |
429 |
Aguarde o intervalo informado antes de repetir |
5xx |
Registre o contexto da falha; avalie uma nova tentativa |
O formato do erro depende da operação
A adoção de Problem Details é gradual. Agenda e Processos utilizam o contrato de erros correspondente; outros recursos podem ter formatos diferentes. Não suponha que todos retornam o mesmo JSON.
Consulte os schemas de resposta da operação e preserve identificadores de requisição recebidos. Uma falha de autenticação pode ser respondida pelo filtro de segurança antes de chegar ao controller.
Limites de requisição
As políticas de limite são configuráveis por ambiente e contexto. Quando a limitação estiver sendo aplicada e houver excesso, a API pode responder 429 e enviar:
Retry-After: tempo de espera, em segundos.RateLimit-Limit: limite aplicado.RateLimit-Remaining: quantidade restante.
O corpo da resposta de limitação inclui code, message, retryAfterSeconds e requestId. Não fixe uma cota numérica na sua integração; use as informações recebidas.
Implemente novas tentativas com critério
Respeite Retry-After quando presente. Para falhas transitórias, use espera progressiva com variação aleatória e um número máximo de tentativas.
Em criações e alterações, confirme o resultado antes de reenviar uma chamada que perdeu a resposta. Uma repetição pode duplicar o efeito. Só use mecanismos de idempotência se estiverem documentados na operação.
Guarde status, rota e identificador da requisição quando disponível. Remova chaves de API e dados sensíveis dos logs.