Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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:
- Azure Communication Services Product Overview - Communication Services product overview.
- Azure Communication Services conceptual documentation - Communication Services Conceptual documentation, this documentation will provide additional information on how to use communication services, including how to use its available SDKs.
- Email Send API - Azure Communication Services email send, this documentation will provide additional information on the API for sending an email through Azure Communication Services.