Timeout changes
Here are more detailed notes for a timeout change to the Engage API (posted 2025-04-10).
Create contact endpoint
The change discussed here concerns the following endpoint:
POST /api/v3/contacts
This endpoint will now enforce a shorter timeout, and will return a "504 RequestTimeOut" status code if a response does not come within about 5 seconds. This is designed to provide more timely feedback in customer-facing flows, such as user sign-ups and onboarding, where quick responses are critical for a smooth experience.
If Engage returns a timeout status code for this endpoint when a request is made, it means that no contact has been created, and all related internal operations will be rolled back. If this happens, the integrating system should then retry the request in accordance with the Engage retry policy. At this link you will find guidance on the recommended retry strategies.
Important
This change is only for API version 3. Version 2 will act as it previously did.
Redeem promotion endpoint
This concerns the following endpoint:
POST /api/v3/promotion-assignments/{assignmentId}/redeem
A similar timeout policy has already been implemented for this endpoint. A request will time out after approximately 4.5 seconds unless the promotion has already passed the "point of no return" (which means it has been marked as redeemed).
Read more about this here.
General policy for timeouts
Engage's general approach is to prioritize successful processing over speed. Most API endpoints are therefore configured with long timeouts to reduce the risk of data corruption. In general, custom client-side timeouts are discouraged unless absolutely necessary.
See Engage's API retry policy here.
If you have any questions about how this change may impact your integration, or would like help adjusting your implementation, reach out to your support team.