diff --git a/include/openthread/coap.h b/include/openthread/coap.h
index f7733d946..99facfd64 100644
--- a/include/openthread/coap.h
+++ b/include/openthread/coap.h
@@ -60,7 +60,7 @@ extern "C" {
 
 #define OT_COAP_MAX_TOKEN_LENGTH 8 ///< Max token length as specified (RFC 7252).
 
-#define OT_COAP_MAX_RETRANSMIT 30 ///< Max retransmit supported by OpenThread.
+#define OT_COAP_MAX_RETRANSMIT 20 ///< Max retransmit supported by OpenThread.
 
 #define OT_COAP_MIN_ACK_TIMEOUT 1000 ///< Minimal ACK timeout in milliseconds supported by OpenThread.
 
@@ -368,6 +368,10 @@ typedef struct otCoapResource
 /**
  * This structure represents the CoAP transmission parameters.
  *
+ * @note mAckTimeout * ((2 ** (mMaxRetransmit + 1)) - 1) * (mAckRandomFactorNumerator / mAckRandomFactorDenominator)
+ *       must not exceed what can be represented by a uint32_t (0xffffffff). This limitation allows OpenThread to
+ *       avoid 64-bit arithmetic.
+ *
  */
 typedef struct otCoapTxParameters
 {
diff --git a/include/openthread/instance.h b/include/openthread/instance.h
index 9783631b6..f47b5c27e 100644
--- a/include/openthread/instance.h
+++ b/include/openthread/instance.h
@@ -53,7 +53,7 @@ extern "C" {
  * @note This number versions both OpenThread platform and user APIs.
  *
  */
-#define OPENTHREAD_API_VERSION (21)
+#define OPENTHREAD_API_VERSION (22)
 
 /**
  * @addtogroup api-instance