Redirecting on HTTP Status Codes

Whenever a request to a proxied URL results in an HTTP error status code, the user is presented with a system error message. For example:

{
  "message": "No route for '/invalid-path'",
  "error": "MethodNotAllowedError",
  "status": 405,
  "timestamp": "2025-07-24T13:40:05.206Z",
  "errorType": "invalid_route"
}

This allows users to get more information about the error, but it can be inconvenient for end-users who expect a more user-friendly experience.

To improve the user experience, you can configure the Link Redirector to redirect users to a specific URL when an error occurs. This is done by defining certain error handling rules in your configuration file. These requests will always be proxied, and the Link Redirector will not return a 404 error for these requests. Instead, it will redirect users to the specified URL based on the error handling rules you define. An additional trace log will be generated to indicate that a proxied request error has occurred.

Configuration

To set up error handling rules, you can add a section to your configuration file under the proxy.errors key. Each rule consists of a status code or range of status codes and a redirect URL.

For example, to redirect users to a custom error page when they encounter a 404 error, you can add the following rule:

proxy:
  errors:
    - status: '404'
      redirect: 'http://example.com/error/404'

This will redirect users to http://example.com/error/404 whenever the Link Redirector encounters a 404 error.

Only for Link Redirector Errors

It should be noted that the Link Redirector will only redirect users to the specified URL if the error occurs because of an error in the Link Redirector itself, such as a 404 or 500 error. If the error is caused by the proxied service, the Link Redirector will not redirect users to the specified URL as this is seen as expected behavior.

Multiple Status Codes

You can also define multiple status codes for a single redirect rule. For example, if you want to redirect users for both 404 and 500 errors to the same custom error page, you can use a comma-separated list of status codes:

proxy:
  errors:
    - status: '404,500'
      redirect: 'http://example.com/error/general'

This will redirect users to http://example.com/error/general for both 404 and 500 errors.

Using Status Code Ranges

Having to define a rule for every single status code can be cumbersome. Instead, you can define ranges of status codes to apply the same redirect rule to multiple codes. To do this, you can use a hyphen to specify a range of status codes. For example, to redirect users for all client errors (400-499) to a custom error page, you can use the following rule:

proxy:
  errors:
    - status: '400-499'
      redirect: 'http://example.com/error/client-error'

This will redirect users to http://example.com/error/client-error for any client error status code, such as 400, 401, 403, and 404.

This can be combined with other rules as well. For example, you can define a rule for error status codes 400-420 and another rule for 500 errors:

proxy:
  errors:
    - status: '400-420,500'
      redirect: 'http://example.com/error/general'

This will redirect users to http://example.com/error/general for any status code in the range of 400 to 420, as well as for 500 errors.