Endpoint Error Policy

Endpoint.errorPolicy controls cache behavior upon a fetch rejection. It uses the rejection error to determine whether it should be treated as 'soft' or 'hard' error.

Soft

Soft errors will continue showing valid data if it exists. However, if no previous data is in the store, it will reject with error. In this case useSuspense() throws the error to be caught by the nearest ErrorBoundary or AsyncBoundary

Hard

Hard errors always reject with error - even when data has previously made available.

'hard' | undefined can both be used to indicate this state.

Fixtures

GET /api/currentTime/:id

▶api/lastUpdated

▶TimePage

import { lastUpdated } from './api/lastUpdated';

export const getUpdated = lastUpdated.extend({
  fetch(this: any, arg) {
    return this.FAKE_ERROR !== undefined
      ? Promise.reject(this.FAKE_ERROR)
      : lastUpdated(arg);
  },
  errorPolicy: error =>
    error.status >= 500 ? ('soft' as const) : ('hard' as const),
  FAKE_ERROR: undefined as Error | undefined,
});

export default function TimePage({ id }) {
  const { updatedAt } = useSuspense(getUpdated, { id });
  React.useEffect(
    () => () => {
      getUpdated.FAKE_ERROR = undefined;
    },
    [updatedAt],
  );
  return (
    <div>
      API time:{' '}
      <time>
        {DateTimeFormat('en-US', { timeStyle: 'long' }).format(
          updatedAt,
        )}
      </time>
    </div>
  );
}

▶ShowTime

🔴 Live Preview

Store▶

Policy for RestEndpoint

Since 500s indicate a failure of the server, we want to use stale data if it exists. On the other hand, something like a 4xx indicates 'user error', which means the error indicates something about application flow - like if a record is deleted, resulting in 404. Keeping the record around would be inaccurate.

Since this is the typical behavior for REST APIs, this is the default policy in @data-client/rest

errorPolicy(error) {
  return error.status >= 500 ? 'soft' : undefined;
}

undefined is another way of specifying a hard error