Request Expiration Time for Asynchronous SOAP API Requests
Asynchronous SOAP API requests support an optional RequestExpirationTime
property. An asynchronous request that includes this property is discarded if the expiration time has passed when it’s picked up from the asynchronous queue for processing.
The expiration time ensures that an API-driven action isn’t executed if it becomes stale, such as when there are transit or queue delays. For example, it ensures that a journey isn’t triggered if a request to update a data extension with contact data isn’t completed within the specified time.
Marketing Cloud Engagement validates the expiration time before adding the request to the queue, which can produce an immediate error response.
The expiration time must be specified as an absolute time. You can specify UTC time, such as 2024-08-05T11:00:00.000Z
, or a time zone offset, such as 2024-09-20T11:00:00.000-08:00
.
A request that doesn’t include the RequestExpirationTime
property never expires. If an asynchronous request includes the RequestExpirationTime
and ScheduledTime
properties, the timestamps in both properties must be in UTC or use the same time zone offset.
The request expiration time property is supported in asynchronous SOAP API requests that include single or batched objects. Only single-part conversations are supported.
Several types of requests don’t support the request expiration time property.
- Asynchronous REST API requests
- Synchronous SOAP and REST API requests
- Requests in which the value of the
CallsInConversation
property is greater than 1 (multi-part conversations)
Asynchronous SOAP API requests that include an expiration time can return errors when the request is added to the queue.
- The API returns error code 228 when the expiration time comes before the current time.
- The API returns error code 229 when the expiration time comes before the time specified in the
ScheduledTime
property. - The API returns error code 231 when the expiration time doesn’t specify a timezone.
- The API returns error code 232 when the time specified in the
ScheduledTime
property doesn’t specify a timezone. - The API returns error code 233 when the request includes the
RequestExpirationTime
property and is part of a multi-part conversation.
If an asynchronous request is picked up for processing after its expiration time has passed, the API returns error code 230, Request Expired
.
For more information about errors related to asynchronous requests, see 200–299 Asynchronous Operation.