Use retry strategies for requests to Experience Edge

The Experience Edge GraphQL endpoint is rate-limited, so there is a limit on the number of requests that can be made within a specific time frame (currently 80 requests per second). If you want to deploy a large Next.js application with static generation (SSG) enabled, you might hit that limit, causing the build process to fail.

At build time, a Next.js Content SDK application sends requests to the endpoint through multiple services. You can implement retry strategies to specify the number of retries the app is permitted (either globally or per service) to successfully generate the production code for a large website.

Each method of the SitecoreClient class, and each of the services it uses to interact with the Sitecore APIs, accept a FetchOptions configuration object. The FetchOptions type defines a set of optional configuration settings that can be included when making GraphQL requests in your application. Two of these options are relevant to retries management:

retries - determines the number of retries permitted.
retryStrategy - lets you define a custom retry strategy to use instead of the application's default one.

Change the number of retries

To specify the number of retries permitted for a service or SitecoreClient method, you can set the value of retries to either a positive integer or 0. The default value is 3, and is set in the Sitecore config file.

The following example demonstrates how to define a FetchOptions object with a custom retries value of 2 and use it with the getPage method:

RequestResponse

const fetchOptions = {
  retries: 2
};
// Using with getPage
const page = await client.getPage(
  '/about',
  { site: 'mysite', language: 'en' },
  fetchOptions
);

You can also define the number of retries using a custom environment variable. However, if you do this, remember to also make the necessary changes to your deployment platform, testing pipelines, and so on.

Modify the default retry strategy

If the number of retries permitted is a positive integer, the affected services will use a default retry strategy based on that number with an exponential back-off/delay factor of 2.

The default retry strategy handles the following response status codes:

429 - too many requests.
502-504 - server errors.
520-524 - Edge-specific errors.

It also supports the following error codes:

ECONNRESET - connection reset.
ETIMEDOUT - timeout.
EPROTO - protocol error.

You can modify the default strategy's status codes, error codes, and back-off/delay factor as needed. The following example shows how to do this for a Next.js app.

To modify the default retry strategy for a Next.js app:

Import the DefaultRetryStrategy class.

RequestResponse

import {
  DefaultRetryStrategy
} from '@content-sdk/nextjs';

In the FetchOptions configuration object, modify the default retry strategy configuration by specifying the desired error codes, status codes, and back-off/delay factor. For example:

RequestResponse

retries: process.env.PROD_GRAPH_QL_SERVICE_RETRIES || 0,
retryStrategy: new DefaultRetryStrategy({
  statusCodes: [402, 409],
  errorCodes: ['ENOTFOUND', 'ETIMEDOUT'],
  factor: 1
}),

Create a custom retry strategy

If you want to configure a retry strategy beyond status codes, error codes, and back-off/delay factor, you can implement a custom strategy class based on the RetryStrategy interface. This interface defines a strategy for retrying GraphQL requests based on errors and attempts, and features two methods named shouldRetry and getDelay.

The shouldRetry method determines whether a request should be retried based on the error and attempt count. It returns a Boolean value and requires the following parameters:

Parameter

Description

error

The error, of type GraphQLClientError, received from the GraphQL request. The GraphQLClientError type handles both ClientError and NodeJS.ErrnoException types.

retries

The number of retries configured.

Default: 3

attempt

The current attempt number.

The getDelay method calculates the delay (in milliseconds) before the next retry, based on the given error and attempt count. It returns the delay for the next retry in milliseconds, and requires the following parameters:

Parameter	Description
`error`	The error, of type `GraphQLClientError`, received from the GraphQL request. The `GraphQLClientError` type handles both `ClientError` and `NodeJS.ErrnoException` types.
`attempt`	The current attempt number.

To create a custom retry strategy for a Next.js app:

Import the RetryStrategy interface.

RequestResponse

import { RetryStrategy, GraphQLClientError,} from '@content-sdk/nextjs';

Declare a new constant of type RetryStrategy and implement the shouldRetry and getDelay methods as needed. For example:

RequestResponse

const customRetryStrategy: RetryStrategy = {
  shouldRetry: (error: GraphQLClientError, retries: number, attempt: number): boolean => true,
  getDelay: (error: GraphQLClientError, attempt: number): number => 1000,
};

Do you have some feedback for us?

If you have suggestions for improving this article,