Use retry strategies for requests to Experience Edge
The Experience Edge GraphQL endpoint is rate-limited, meaning there is a limit on the number of requests that can be made within a specific time frame (currently 80 requests per second). While building or deploying a large Next.js application with static generation (SSG) enabled, you might hit that limit, causing the build process to fail.
At build time, the Next.js application sends requests to the endpoint through multiple services. You can implement retry strategies and specify the number of retries (either globally or for each service) to successfully generate the production code for a large website.
Retry strategies are available in JSS version 20 from 20.3 onwards and in version 21 from 21.6.3 onwards.
Set the number of retries
You can configure a specific number of retries globally or per service.
Set the number of retries globally
Next.js JSS applications use the GRAPH_QL_SERVICE_RETRIES
environment variable to set the number of GraphQL request retries for all services that use a GraphQL endpoint (the Layout, Dictionary, and Error Page services). Retries are initially set to 3 based on the default value of the environment variable. You can disable retries for all services by setting that value to 0.
To set the number of retries globally:
-
Update the value of the
GRAPH_QL_SERVICE_RETRIES
environment variable to the desired value (a positive integer, or 0 to disable).
Set the number of retries per service
If you want to specify a different number of retries for each service, you can either set the value of each service's retries
option to a positive integer or 0, or define custom environment variables for each service. In either case, make changes to the following files as needed:
-
For the Layout service:
src/lib/layout-service-factory.ts
. -
For the Dictionary service:
src/lib/dictionary-service-factory.ts
. -
For the Error Page service:
src/pages/404.tsx
andsrc/pages/500.tsx
.
If you add environment variables or modify the value of GRAPH_QL_SERVICE_RETRIES
, remember to make the necessary changes in your deployment platform, testing pipelines, and so on.
Modify the default retry strategy
If you've set the number of retries to 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 error -
ETIMEDOUT
- timeout error -
EPROTO
- protocol error
You can modify the default strategy's list of status codes, error codes, and back-off/delay factor as needed.
To modify the default retry strategy:
-
In your service factory file, for example,
/src/lib/dictionary-service-factory.ts
, import theDefaultRetryStrategy
class:RequestResponseimport { DefaultRetryStrategy } from '@sitecore-jss/sitecore-jss-nextjs';
-
In the GraphQL service options, modify the default retry strategy configuration by specifying the desired error codes, status codes, and delay factor. If the default configuration is not present, you will need to add it first. For example:
RequestResponseretries: (process.env.GRAPH_QL_SERVICE_RETRIES && parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) || 0, retryStrategy: new DefaultRetryStrategy({ statusCodes: [402, 409]; errorCodes: ['ENOTFOUND', 'ETIMEDOUT']; factor: 1})
Create a custom strategy
If you want to customize the retry strategy beyond status codes, error codes, and delay factor, you can implement your own retry strategy class based on the RetryStrategy
interface.
The interface defines a strategy for retrying GraphQL requests based on errors and attempts. It defines two methods as follows:
-
shouldRetry
- determines whether a request should be retried based on theerror
andattempt
count. It returns a Boolean value, and requires the following parameters:Parameter
Description
error
The error of the
GraphQLClientError
type received from the GraphQL request. TheGraphQLClientError
type handles bothClientError
andNodeJS.ErrornoException
types.retries
The number of retries configured.
Default: 3
attempt
The current attempt number.
-
getDelay
- calculates the delay (in milliseconds) before the next retry, based on the givenerror
andattempt
count. It returns the delay for the next retry in milliseconds, and requires the following parameters:Parameter
Description
error
The error of the
GraphQLClientError
type received from the GraphQL request. TheGraphQLClientError
type handles bothClientError
andNodeJS.ErrornoException
types.attempt
The current attempt number.
To create a custom retry strategy:
-
In your service factory file, for example,
/src/lib/dictionary-service-factory.ts
, import theRetryStrategy
interface:RequestResponseimport { RetryStrategy, ClientError, GraphQLClientError, } from '@sitecore-jss/sitecore-jss-nextjs';
-
Declare a new constant of the
RetryStrategy
type and implement theshouldRetry
andgetDelay
methods. For example:RequestResponseconst customRetryStrategy: RetryStrategy = { shouldRetry: (error: GraphQLClientError, retries: number, attempt: number): boolean => true, // Replace this with your own implementation getDelay: (error: GraphQLClientError, attempt: number): number => 1000 // Replace this with your own implementation };
-
Add your custom retry strategy to the GraphQL service options. For example:
RequestResponsenew GraphQLDictionaryService({ siteName, clientFactory, retries: (process.env.GRAPH_QL_SERVICE_RETRIES && parseInt(process.env.GRAPH_QL_SERVICE_RETRIES, 10)) || 0, retryStrategy: customRetryStrategy })