Depois de decidir usar a API de Mensageria, é importante considerar alguns aspectos técnicos, como os limites de velocidade, os possíveis erros e as estratégias de novas tentativas e reconexão quando necessário.
A seguir ,você encontrará todas essas informações para poder consultá-las e navegar por elas com facilidade.
Rate Limiting
A API tem limites de velocidade para proteger a estabilidade do serviço.
Limites recomendados
| Recurso | Limite | Janela | Observações |
| POST /auth | 10 requests | por minuto por IP | Armazene o Bearer token em cache até a expiração. |
| POST /conversation/messages | 60 requests | por minuto por usuário (hash) | Um fluxo normal não deveria superar 10–15 msgs/min. |
| POST /conversation/close | 10 requests | por minuto por usuário (hash) | Chame apenas ao finalizar. |
 Valores orientativos. Consulte a equipe de CSM para limites exatos de acordo com o contrato.
|
Erros da API HTTP
| HTTP Status |
Cenário |
Ação recomendada |
| 401 Unauthorized | Bearer token expirado ou inválido | Obtenha um novo token via /auth e tente novamente |
| 400 Bad Request | Request malformado ou campos faltando | Verifique o body e os headers |
| 404 Not Found | Recurso não encontrado | Verifique a URL do endpoint |
| 500 Internal Server Error | Erro do servidor | Tente novamente com backoff exponencial; se persistir, contate o suporte |
Erros conversacionais (HTTP 200)
O código HTTP 200 confirma que a solicitação ao serviço foi bem-sucedida do ponto de vista do protocolo HTTP. No entanto, é possível que o fluxo conversacional apresente um erro se o conteúdo da resposta não corresponder ao esperado para o caso de uso implementado.
Estratégia de Retry e Reconexão
| Quando tentar novamente | ||
| Cenário |
Tentar novamente? |
Estratégia |
| HTTP 500 |
Sim |
Backoff exponencial de 1 s, 2 s, 4 s. Máx. 3 tentativas. |
| HTTP 401 |
Sim |
Obtenha um novo token e tente novamente 1 vez. |
| HTTP 400 |
Não |
Corrija o request; não tente novamente do mesmo jeito. |
| HTTP 404 |
Não |
Verifique a URL; não tente novamente |
| Timeout de rede |
Sim |
Tente novamente 1 vez; se falhar, exiba um erro. |
| Error conversacional (200) | Não |
Siga o fluxo de acordo com os complementos. |
O que não fazer
- Não tente reenviar uma mensagem no meio do fluxo com o mesmo sentence se a sessão expirou.
- Não tente novamente indefinidamente (máx. 3 tentativas).
- Não tente novamente se o erro for conversacional (HTTP 200).
- Não crie várias sessões em paralelo para o mesmo usuário.
Tratamento de HTTP 429: Too Many Requests. Limite de velocidade excedido.
- Espere o tempo indicado em Retry-After (se estiver presente).
- Se não houver Retry-After, espere 60 segundos.
- Implementar una cola (queue) del lado del cliente para no exceder los límites.
Boas práticas
- Armazene o Bearer token em cache e reutilize-o até que expire.
- Não envie mensagens em rajada sem throttle.
- Implemente debounce no frontend para cliques rápidos.
Veja também:
FAQs e boas práticas sobre a API de Mensageria