| <div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/Apache_RocketMQ_logo.svg.png" alt="My Site Logo" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/Apache_RocketMQ_logo.svg.png" alt="My Site Logo" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">Apache RocketMQ</b></a></div><div class="navbar__items navbar__items--right"><a href="https://github.com/apache/rocketmq" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link"><svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" class="iconLanguage_nlXk"><path fill="currentColor" d="M12.87 15.07l-2.54-2.51.03-.03c1.74-1.94 2.98-4.17 3.71-6.53H17V4h-7V2H8v2H1v1.99h11.17C11.5 7.92 10.44 9.75 9 11.35 8.07 10.32 7.3 9.19 6.69 8h-2c.73 1.63 1.73 3.17 2.98 4.56l-5.09 5.02L4 19l5-5 3.11 3.11.76-2.04zM18.5 10h-2L12 22h2l1.12-3h4.75L21 22h2l-4.5-12zm-2.62 7l1.62-4.33L19.12 17h-3.24z"></path></svg>English</a><ul class="dropdown__menu"><li><a href="/zh/docs/featureBehavior/10consumerretrypolicy" target="_self" rel="noopener noreferrer" class="dropdown__link" lang="zh">简体中文</a></li><li><a href="/docs/featureBehavior/10consumerretrypolicy" target="_self" rel="noopener noreferrer" class="dropdown__link dropdown__link--active" lang="en">English</a></li></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link">Docs</a><ul class="dropdown__menu"><li><a aria-current="page" class="dropdown__link dropdown__link--active" href="/docs/">5.0</a></li><li><a class="dropdown__link" href="/docs/4.x/">4.x</a></li></ul></div><a class="navbar__item navbar__link" href="/download">Download</a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link">Blog</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/blog">User Cases</a></li><li><a class="dropdown__link" href="/events">Activity</a></li><li><a class="dropdown__link" href="/release-notes">Change Log</a></li><li><a class="dropdown__link" href="/news">RocketMQ News</a></li></ul></div><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link">Community</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/contact">Join Community</a></li><li><a class="dropdown__link" href="/origin">Origin</a></li><li><a class="dropdown__link" href="/team">Teams</a></li><li><a class="dropdown__link" href="/docs/contributionGuide/01how-to-contribute">Contributions</a></li><li><a class="dropdown__link" href="/enterprise">Enterprises</a></li></ul></div><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebarViewport_Xe31"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/">Introduction</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/quickStart/01quickstart">Quick Start</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/domainModel/01main">Domain Model</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" aria-expanded="true" href="/docs/featureBehavior/01normalmessage">Feature Behavior</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/01normalmessage">Normal Message</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/02delaymessage">Delay Message</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/03fifomessage">Ordered Message</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/04transactionmessage">Transaction Message</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/05sendretrypolicy">Sending Retry and Throttling Policy</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/06consumertype">Consumer Types</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/07messagefilter">Message Filtering</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/08consumerloadbalance">Consumer Load Balancing</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/09consumerprogress">Consumer Progress Management</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/featureBehavior/10consumerretrypolicy">Consumption Retry</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/featureBehavior/11messagestorepolicy">Message Storage and Cleanup</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/deploymentOperations/01deploy">Deployment & Operations</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/observability/01metrics">Observability</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/sdk/01overview">Client SDK</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/bestPractice/01bestpractice">Best Practice</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/eventbridge/01RocketMQEventBridgeConcepts">RocketMQ EventBridge</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/mqtt/01RocketMQMQTTOverview">RocketMQ MQTT</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/connect/01RocketMQ Connect Overview">RocketMQ Connect</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/streams/01RocketMQ Streams Overview">RocketMQ Streams</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/contributionGuide/01how-to-contribute">Contribution Guide</a></div></li></ul></nav></div></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Feature Behavior</span><meta itemprop="position" content="1"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Consumption Retry</span><meta itemprop="position" content="2"></li></ul></nav><span class="theme-doc-version-badge badge badge--secondary">Version: 5.0</span><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><h1>Consumption Retry</h1><p>If a message fails to be consumed, Apache RocketMQ redelivers the message based on a consumption retry policy. This helps remove some faults. This topic describes the working mechanism, version compatibility, and usage notes of the consumption retry feature.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="scenarios">Scenarios<a href="#scenarios" class="hash-link" aria-label="Direct link to heading" title="Direct link to heading"></a></h2><p>The consumption retry feature of Apache RocketMQ ensures consumption integrity that may be affected by the failure of a business processing logic. This feature is a protective measure against business logic failures. It cannot be used to control the business process.</p><p>The feature is suitable for use in the following scenarios:</p><ul><li><p>The business fails because of the message content. For example, the transaction status is not returned and the business is expected to be restored within a specific period of time.</p></li><li><p>The cause of consumption failure does not affect business continuity. The failure has a small possibility of occurring and subsequent messages are very likely to be delivered and consumed as expected. In these cases, you can use the retry mechanism to redeliver the message to avoid blocking the process.</p></li></ul><p>Do not use the feature in the following scenarios:</p><ul><li><p>Consumption failure is used as a condition to divert message flows in the processing logic. The processing logic assumes that many messages will fail to be consumed.</p></li><li><p>Consumption failure is used to limit the rate of message processing. Rate limiting should be used to temporarily stack excessive messages in the queue for later processing instead of making the messages enter the retry link.</p></li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="purpose">Purpose<a href="#purpose" class="hash-link" aria-label="Direct link to heading" title="Direct link to heading"></a></h2><p>A common issue of message middleware in asynchronous decoupling is how to ensure the integrity of the entire call link if the downstream service fails to process messages. As a financial-grade reliable message middleware service, Apache RocketMQ uses a well-designed message acknowledgement and retry mechanism to ensure that every message is processed according to business expectations.</p><p>Understanding the message acknowledgement and retry mechanism of Apache RocketMQ helps solve the following issues:</p><ul><li><p>How to ensure that every message is processed: You can ensure that every message is processed based on their consumer logic and business statuses are consistent.</p></li><li><p>How to ensure that the status of messages that are being processed are correct when an exception occurs: You can ensure the correct message status when an exception, such as power failure, occurs.</p></li></ul><h2 class="anchor anchorWithStickyNavbar_LWe7" id="policy-overview">Policy overview<a href="#policy-overview" class="hash-link" aria-label="Direct link to heading" title="Direct link to heading"></a></h2><p>When the consumption retry feature is enabled, the Apache RocketMQ broker resends a message when the message fails to be consumed. If the message fails to be consumed even after a specified number of retries, the broker sends the message to the dead-letter queue.</p><p><strong>Trigger conditions</strong></p><ul><li><p>A message fails to be consumed. In this case, the consumer returns a failure status or the system throws an exception.</p></li><li><p>A timeout error occurs or a message stays in a push consumer queue for an excessive period of time.</p></li></ul><p><strong>Behaviors</strong></p><ul><li><p>Retry process state machine: controls the state and the change logic of messages in the retry process.</p></li><li><p>Retry interval: the time that elapses from when a consumption failure or timeout occurs to when the message is retried.</p></li><li><p>Maximum retries: the maximum number of times that a message can be retried for consumption.</p></li></ul><p><strong>Policy differences</strong></p><p>Message retry policies use different retry mechanisms and configuration methods based on the consumer type. The following table describes the differences between the policies.</p><table><thead><tr><th>Consumer type</th><th>Retry process state machine</th><th>Retry interval</th><th>Maximum number of retries</th></tr></thead><tbody><tr><td>PushConsumer</td><td><em> Ready </em> Inflight <em> WaitingRetry </em> Commit * DLQ</td><td>Specified in the metadata when a consumer group is created. <em> Unordered messages: incremental </em> Ordered messages: fixed</td><td>Specified in the metadata when a consumer group is created.</td></tr><tr><td>SimpleConsumer</td><td><em> Ready </em> Inflight <em> Commit </em> DLQ</td><td>Specified in the InvisibleDuration parameter in the API.</td><td>Specified in the metadata when a consumer group is created.</td></tr></tbody></table><p>For more information about retry policies, see <a href="#section-qqo-bil-rc6">Retry policy for push consumers</a> and <a href="#section-my2-2au-7gl">Retry policy for simple consumers</a>.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="retry-policy-for-pushconsumer">Retry policy for PushConsumer<a href="#retry-policy-for-pushconsumer" class="hash-link" aria-label="Direct link to heading" title="Direct link to heading"></a></h2><p><strong>Retry process state machine</strong></p><p>When a push consumer consumes a message, the message can be in one of the following states:<img loading="lazy" alt="State machine for push consumers" src="/assets/images/retrymachinestatus-37ddbd0a20b8736e34bb88f565945d16.png" width="837" height="543" class="img_ev3q"></p><ul><li>Ready The message is waiting to be consumed on the Apache RocketMQ broker.</li></ul><ul><li>Inflight The message has been obtained and is being consumed by the consumer. However, the consumption result has not been returned.</li></ul><ul><li>WaitingRetry This state is exclusive to push consumers. The message fails to be consumed or a timeout error occurs when the broker waits for the consumer to return the consumption status. In these cases, the consumption retry logic is triggered. If the maximum number of retries is not reached, the message goes back to the Ready state after the retry interval elapses. Messages that are in the Ready state can be consumed again. You can increase the interval between retries to prevent frequent retries.</li></ul><ul><li>Commit The message is consumed. After the consumer returns a success response, the state machine can be terminated.</li></ul><ul><li>DLQ A preventive measure for the consumption logic. If the message fails to be consumed even after the maximum number of retries is reached, the message is no longer retried and is sent to the dead-letter queue. You can consume messages in a dead-letter queue to restore your business.</li></ul><p>When a message is retried, its state changes from Ready to Inflight and then to WaitingRetry. The interval between two consumptions is the sum of the actual time spent on consumption and the retry interval. The maximum consumption interval is specified by a system parameter on the broker and cannot be exceeded. <img loading="lazy" alt="Retry interval" src="/assets/images/retrytimeline-27247ef53fbcf08c745b9f7d356de6f9.png" width="1060" height="310" class="img_ev3q"></p><p><strong>Maximum number of retries</strong></p><p>The maximum number of retries for a push consumer is specified in the metadata when the consumer group is created. For more information, see <a href="/docs/domainModel/07consumergroup">Consumer groups</a>.</p><p>For example, if the maximum number of retries is three, the message can be delivered four times: one original attempt and three retries.</p><p><strong>Retry interval</strong></p><ul><li><p>Unordered messages (messages that are not ordered messages): incremental. The following table describes the details.</p><table><thead><tr><th>Retry number</th><th>Interval</th><th>Retry number</th><th>Interval</th></tr></thead><tbody><tr><td>1</td><td>10 seconds</td><td>9</td><td>7 minutes</td></tr><tr><td>2</td><td>30 seconds</td><td>10</td><td>8 minutes</td></tr><tr><td>3</td><td>1 minute</td><td>11</td><td>9 minutes</td></tr><tr><td>4</td><td>2 minutes</td><td>12</td><td>10 minutes</td></tr><tr><td>5</td><td>3 minutes</td><td>13</td><td>20 minutes</td></tr><tr><td>6</td><td>4 minutes</td><td>14</td><td>30 minutes</td></tr><tr><td>7</td><td>5 minutes</td><td>15</td><td>1 hour</td></tr><tr><td>8</td><td>6 minutes</td><td>16</td><td>2 hours</td></tr></tbody></table></li></ul><div class="theme-admonition theme-admonition-info alert alert--info admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>info</div><div class="admonitionContent_S0QG"><p>If the number of retries exceeds 16, the interval of each subsequent retry is 2 hours.</p></div></div><ul><li>Ordered messages: fixed. For more information, see<a href="/docs/introduction/03limits">Parameter limits</a>.</li></ul><p><strong>Example</strong></p><p>For push consumers, a message retry is triggered only by the status code of consumption failure. Unexpected exceptions are also captured by the SDK.</p><div class="language-java codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-java codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain"> SimpleConsumer simpleConsumer = null;</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> // Consumption example: Consume normal messages as a push consumer and trigger a message retry by using a consumption failure. </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> MessageListener messageListener = new MessageListener() {</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> @Override</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> public ConsumeResult consume(MessageView messageView) {</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> System.out.println(messageView);</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> // Retry the message until the maximum number of retries is reached. </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> return ConsumeResult.FAILURE;</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> };</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="retry-policy-for-simpleconsumer">Retry policy for SimpleConsumer<a href="#retry-policy-for-simpleconsumer" class="hash-link" aria-label="Direct link to heading" title="Direct link to heading"></a></h2><p><strong>Retry process state machine</strong></p><p>When a simple consumer consumes a message, the message can be in one of the following states:<img loading="lazy" alt="Push consumer state machine" src="/assets/images/simplemachinestatus-1844bd0115b315e32661cf20b1732db0.png" width="835" height="543" class="img_ev3q"></p><ul><li><p>Ready The message is waiting to be consumed on the Apache RocketMQ broker.</p></li><li><p>Inflight The message has been obtained and is being consumed by the consumer. However, the consumption result has not been returned.</p></li><li><p>Commit The message is consumed. After the consumer returns a success response, the state machine can be terminated.</p></li><li><p>DLQ A preventive measure for the consumption logic. If the message fails to be consumed even after the maximum number of retries is reached, the message is no longer retried and is sent to the dead-letter queue. You can consume messages in a dead-letter queue to restore your business.</p></li></ul><p>The retry interval is fixed and pre-allocated. It is configured in the InvisibleDuration parameter by the consumer when the consumer calls the API. The parameter specifies the maximum processing duration of the message. When a message is retried, the value of the parameter is reused. You do not need to configure the interval for the subsequent retries. |
| <img loading="lazy" alt="Modify the InvisibleDuration value" src="/assets/images/changeInvisibletime-769fd45237e26f2ff333ee1149e66d47.png" width="689" height="333" class="img_ev3q"></p><p><strong>Maximum number of retries</strong></p><p>The maximum number of retries for a simple consumer is specified in the metadata when the consumer group is created. For more information, see <a href="/docs/domainModel/07consumergroup">Consumer groups</a>.</p><p><strong>Message retry interval</strong></p><p>Message retry interval = InvisibleDuration value − Actual duration of message processing</p><p>The consumption retry interval is therefore controlled by the InvisibleDuration value. For example, if the InvisibleDuration value is 30 ms and a consumption failure is returned 10 ms after the processing starts, the time to the next retry is 20 ms, which means that the retry interval is 20 ms. If no consumption result is returned within 30 ms, a timeout error occurs and a retry is triggered. Then, the retry interval is 0 ms.</p><p><strong>Examples</strong></p><p>Simple consumers need only to wait for a message to be retried.</p><div class="language-java codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-java codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#393A34"><span class="token plain"> // Consumption example: Consume normal messages as a simple consumer. If you want a message to be retried, do not process the message. Wait for it to time out, and the broker retries it automatically. </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> List<MessageView> messageViewList = null;</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> try {</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> messageViewList = simpleConsumer.receive(10, Duration.ofSeconds(30));</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> messageViewList.forEach(messageView -> {</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> System.out.println(messageView);</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> // If you want a message to be retried after it fails to be consumed, ignore the failure and wait for the message to be visible. Then try to obtain it again from the broker. </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> });</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> } catch (ClientException e) {</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> // If the message fails to be pulled due to throttling or other reasons, you must re-initiate the request to obtain the message. </span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> e.printStackTrace();</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> }</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="usage-notes">Usage notes<a href="#usage-notes" class="hash-link" aria-label="Direct link to heading" title="Direct link to heading"></a></h2><p><strong>Do not use consumption retry to deal with consumption throttling</strong></p><p>As mentioned in <a href="#section-d2i-0sk-rtf">Scenarios</a>, message retry is suitable for scenarios where failure of business processing and message consumption is a small-possibility event. Message retry is not suitable for scenarios where the failure continues, such as consumption throttling.</p><ul><li><p>Incorrect example:Return consumption failures to trigger retries when the current consumption rate is higher than the upper limit.</p></li><li><p>Correct example:Obtain and consume messages at a later time if the current consumption rate is higher than limited.</p></li></ul><p><strong>Set a proper number of retries to avoid infinite retries</strong></p><p>Although Apache RocketMQ supports custom numbers of consumption retries, we recommend that you set a small number of retries and a long retry interval to reduce the burden on the system. Avoid a large number of retries or infinite retries.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="theme-doc-footer-edit-meta-row row"><div class="col"><a href="https://github.com/apache/rocketmq-site/tree/new-official-website/versioned_docs/version-5.0/04-featureBehavior/10consumerretrypolicy.md" target="_blank" rel="noreferrer noopener" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_vwxv"></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/featureBehavior/09consumerprogress"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Consumer Progress Management</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/featureBehavior/11messagestorepolicy"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Message Storage and Cleanup</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#scenarios" class="table-of-contents__link toc-highlight">Scenarios</a></li><li><a href="#purpose" class="table-of-contents__link toc-highlight">Purpose</a></li><li><a href="#policy-overview" class="table-of-contents__link toc-highlight">Policy overview</a></li><li><a href="#retry-policy-for-pushconsumer" class="table-of-contents__link toc-highlight">Retry policy for PushConsumer</a></li><li><a href="#retry-policy-for-simpleconsumer" class="table-of-contents__link toc-highlight">Retry policy for SimpleConsumer</a></li><li><a href="#usage-notes" class="table-of-contents__link toc-highlight">Usage notes</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Learn</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/domainModel/01main">Introduction</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/quickStart/01quickstart">Installation</a></li><li class="footer__item"><a class="footer__link-item" href="/version">Migration from 4.x to 5.0</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://twitter.com/ApacheRocketMQ" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://github.com/apache/rocketmq" target="_blank" rel="noopener noreferrer" class="footer__link-item">Github</a></li><li class="footer__item"><a href="https://github.com/apache/rocketmq" target="_blank" rel="noopener noreferrer" class="footer__link-item">Help</a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/blog">Blog</a></li><li class="footer__item"><a class="footer__link-item" href="/release-notes">Changelog</a></li><li class="footer__item"><a href="https://github.com/apache/rocketmq" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://twitter.com/docusaurus" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">Legal</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://www.apache.org/licenses/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Licenses<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://www.apache.org/security/" target="_blank" rel="noopener noreferrer" class="footer__link-item">Security<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Thanks<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener noreferrer" class="footer__link-item">Sponsorship<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="margin-bottom--sm"><a href="https://rocketmq.apache.org/" rel="noopener noreferrer" class="footerLogoLink_BH7S"><img src="/img/Apache_RocketMQ_logo.svg.png" alt="Meta Open Source Logo" class="themedImage_ToTc themedImage--light_HNdA footer__logo"><img src="/img/Apache_RocketMQ_logo.svg.png" alt="Meta Open Source Logo" class="themedImage_ToTc themedImage--dark_i4oU footer__logo"></a></div><div class="footer__copyright">Copyright © 2022 The Apache Software Foundation. Licensed under the Apache License, Version 2.0.</div></div></div></footer></div> |
