grammY

Retry API Requests (auto-retry)

Consider using the throttler plugin instead.

This plugin is an API transformer function, which means that it let’s you intercept and modify outgoing HTTP requests on the fly. More specifically, this plugin will automatically detect if an API requests fails with a retry_after value, i.e. because of rate limiting. It will then catch the error, wait the specified period of time, and then retry the request.

Be Gentle With the Bot API Server

Telegram is generously providing information about how long your bot must wait before the next request. Using the auto-retry plugin will allow your bot to perform better during load spikes, as the requests will not simply fail because of the flood limit. However, auto-retry should not be used if you want to avoid hitting rate limits on a regular basis. If you regularly cross the threshold of how many requests you may perform, Telegram may take measures such as restricting or banning your bot.

You can install this plugin on the bot.api object:

import { autoRetry } from "@grammyjs/auto-retry";

// Use the plugin.
bot.api.config.use(autoRetry());

const { autoRetry } = require("@grammyjs/auto-retry");

// Use the plugin.
bot.api.config.use(autoRetry());

import { autoRetry } from "https://esm.sh/@grammyjs/auto-retry";

// Use the plugin.
bot.api.config.use(autoRetry());

If you now call e.g. sendMessage and run into a rate limit, it will look like the request just takes unusually long. Under the hood, multiple HTTP requests are being performed, with the appropriate delays in between.

You may pass an options object that specifies a maximum number of retries (maxRetryAttempts, default: 3), or a threshold for a maximum time to wait (maxDelaySeconds, default: 1 hour).

As soon as the maximum number of retries is exhausted, subsequent errors for the same request will not be retried again. Instead, the error object from Telegram is passed on, effectively failing the request with a GrammyError.

Similarly, if the request ever fails with retry_after larger than what is specified by the option maxDelaySeconds, the request will fail immediately.

autoRetry({
  maxRetryAttempts: 1, // only repeat requests once
  maxDelaySeconds: 5, // fail immediately if we have to wait >5 seconds
});

You can use retryOnInternalServerErrors to include all other internal server errors by Telegram (status code >= 500) in the above procedure. Those errors will be retried immediately, but they also respect the maxRetryAttempts option.

Plugin Summary