Error Mapping and Technical Considerations for the Messaging API

Once you decide to use the Messaging API, it’s important to consider certain technical aspects, such as rate limits, potential errors, and retry and reconnection strategies when necessary.

Below you’ll find all this information so you can easily refer to it and navigate through it.

Rate Limiting

The API has rate limits to ensure service stability.

Recommended Limits

Resource	Limit	Window	Notes
POST /auth	10 requests	per minute per IP	Cache the Bearer token until it expires.
POST /conversation/messages	60 requests	per minute per user (hash)	Normal traffic should not exceed 10–15 msgs/min.
POST /conversation/close	10 requests	per minute per user (hash)	Call only upon completion.

These are approximate values. Consult the CSM team for exact limits as specified in your agreement.

HTTP API Errors

HTTP Status	Scenario	Recommended Action
401 Unauthorized	Expired or invalid Bearer token	Obtain a new token via /auth and retry
400 Bad Request	Malformed request or missing fields	Verify the body and headers
404 Not Found	Resource not found	Verify the endpoint URL
500 Internal Server Error	Server error	Retry with exponential backoff; if the error persists, contact support

Conversational Errors (HTTP 200)

The HTTP 200 code confirms that the request to the service was successful from the perspective of the HTTP protocol. However, the conversational flow may still contain an error if the response content does not match what is expected for the implemented use case.

Retry and Reconnection Strategy

When to Retry
Scenario	Retry?	Strategy
HTTP 500	Yes	Exponential backoff: 1s, 2s, 4s. Max. 3 attempts.
HTTP 401	Yes	Obtain a new token and retry once.
HTTP 400	No	Correct the request; do not retry as-is.
HTTP 404	No	Verify the URL; do not retry.
Network timeout	Yes	Retry once; if it fails, display an error.
Conversational error (200)	No	Follow the flow according to the complements

What Not to Do

Do not retry a message in the middle of a flow with the same sentence if the session has expired.
Do not retry indefinitely (max. 3 attempts).
Do not retry if the error is conversational (HTTP 200).
Do not create multiple parallel sessions for the same user.

Handling HTTP 429: Too Many Requests. Rate limit exceeded.

Wait for the time specified in Retry-After (if present).
If there is no Retry-After, wait 60 seconds.
Implement a client-side queue to avoid exceeding limits.

Best Practices

Cache the Bearer token and reuse it until it expires.
Do not send bursts of messages without throttling.
Implement debounce in the frontend for rapid clicks.