Enable retries for requests to the XM Cloud Experience Edge GraphQL endpoint

Current version: 21.5

The Experience Edge GraphQL endpoint in XM Cloud 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/second). When building or deploying a large Next.js application with static generation (SSG) enabled, you might hit the limitation, and the build process will fail. At build time, the Next.js application configured to use GraphQL sends requests to the endpoint through multiple services.

To successfully generate the production code for a large website, you can enable retries for the GraphQL client in your Next.js application.

You can configure a specific number of retries globally or per service.

Next.js JSS applications use the GRAPH_QL_SERVICE_RETRIES environment variable for setting the number of GraphQL request retries for all services that use the GraphQL endpoint (Layout, Dictionary, and Error Page services). By default, the value of this environment variable is 0.

To enable request retries:

  • Update the value of the GRAPH_QL_SERVICE_RETRIES environment variable to a positive integer.

    Depending on your deployment practices and setup, you might need to update the variable's value in multiple locations, such as your Next.js application's .env file(s), your deployment service, pipelines, and so on.

If you need to specify a different number of retries for each service, you can change the value of the service's retries option or define custom environment variables for each service.

Depending on which approach you prefer, replace the existing retries value with a hard-coded positive integer or the environment variable name in the following files:

  • For the Layout Service, in the src/lib/layout-service-factory.ts file.

  • For the Dictionary Service, in the src/lib/dictionary-service-factory.ts file.

  • For the Error Page Service, in the src/pages/404.tsx and src/pages/500.tsx files.


If you define custom environment variables, for example, GRAPH_QL_LAYOUT_SERVICE_RETRIES, you must remember to add the variables to XM Cloud, your deployment service, pipelines, and so on.

For additional information on working with environment variables in XM Cloud, refer to:

Do you have some feedback for us?

If you have suggestions for improving this article,