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.