Share via


Repeatability of requests

Applies to: ACS Email (Email Send API), ACS Rooms

POST APIs are not idempotent by definition. In order to make them behave in an idempotent manner, we support repeatable requests according to the OASIS Repeatable Requests Version 1.0 specification. To support this, customers need to specify two mandatory headers in their POST request:

  • Repeatability-Request-Id
  • Repeatability-First-Sent

Repeatability-Request-Id header

The value of this header identifies the request uniquely with a GUID.

Repeatability-First-Sent header

The value of this header represents the time stamp when the original request was first sent. The value should be specified in UTC in IMF-fixdate format. We only track requests for a specified duration (currently, the tracked duration is 5 minutes). Any requests with a first-sent value prior to that are considered potentially unsafe to re-execute and will return a 412 (Pre-condition failed) error.

Repeatability in ACS SDKs

Repeatability headers are automatically generated, added and sent to the API when using any of our ACS SDK libraries.

Repeatable request response codes

Detailed information about various status codes for repeatable requests are included in the table below.

Repeatability-Request-ID Repeatability-First-Sent Repeatability Result Response Statuscode
Valid GUID Invalid format Rejected 400
Invalid format Valid Date Rejected 400
Invalid format Invalid format Rejected 400
Valid Outside tracking duration Rejected 412 (Precondition failed)
Valid new/unrepeated request Within tracking duration Accepted Status code from normal execution
Valid repeated request Within tracking duration, but doesn't match previous request Rejected 400
Valid repeated request Within tracking duration, matches previous request Accepted In Email Send API:
- If original request is still in progress: 409
- If original request's status code was 2xx or 4xx, return that status code.
- If original request's status code was 5xx, return status code from re-execution of the request.

Troubleshooting

If you have sent a request with a first sent timestamp that is within the last 5 minutes, but still receive a 412 (Precondition failed) error with message "Repeatability first sent header was not in 5 minutes window.", then make sure to check that your client computer's clock is synced to the time server.

See Also

For additional information on Azure Communication Services, you can also review our other documentation sources: