Is your feature request related to a problem? Please describe.

@prismicio/client throws a RefExpiredError when a request's ref is expired. The client typically fetches the active ref automatically before sending a content request, but some environments cache the ref. For example, Next.js caches fetch() requests, which could result in a request made with a stale ref.

Because @prismicio/client handles fetching the ref automatically, developers are not expecting the ref to be expired. Instead, they expect the client to fetch the content they requested.

Describe the solution you'd like

Currently, the error provides the master ref as part of the message:

The provided ref is no longer accessible, it has expired. Master ref is: xxxxxxxxxxxxxx

We can extract the master ref from this error message and retry the request with the new ref.

When the client retries a request, the developer should be notified through a console warning.

If the retried request also has an expired ref, we can continue retrying until a valid ref is found. We can limit the number of retries to prevent infinite loops.

When a developer explicitly provides a ref, such as through defaultParams, a preview session, or on a per-query basis, the ref should be used as provided. The retry logic and console message should be skipped. This avoids a case where a developer is sure they want to use a specific ref. We should respect that decision and let them handle the error or change their code.

Describe alternatives you've considered

Developers can already catch RefExpiredError and handle the retry themselves. That is a solution to a leaky abstraction and is not something we should ask developers to do.

Developers can also configure their environments to not cache requests to /api/v2. This kind of configuration can be tricky to set up, however, and may introduce additional headaches.

Additional context

This error most often comes from Next.js websites using the App Router. The App Router caches fetch() requests when configured properly, and we recommend caching all Prismic requests.