Custom error page when origin not available


Customers often have friendly or prettier 503 error pages to serve for the following scenarios:

  • When origin returns a response status greater than 500
  • When origin is down (i.e unhealthy, timeout, etc)

To serve your custom error page in both scenarios there needs to be logic in both vcl_fetch and vcl_error.

Custom error page for responses greater than 500

We have a help guide that shows how to implement a custom response with a cache condition. The cache condition will tell Fastly to serve the custom page depending on the response status from origin.

Custom error page when the origin is unavailable

When there is no backend response, Fastly will go to vcl_error for instructions. Custom VCL in this section will instruct Fastly to serve a custom page if we can’t reach the origin. (If custom vcl is not enabled on your account, email

Add the following to vcl_error:

sub vcl_error {

#FASTLY error

 /* handle 5XXs*/
 if (obj.status >= 500 && obj.status < 600) {

   /* include your HTML response here */
   synthetic {"<!DOCTYPE html><html>Please replace this text with the error page you would like to serve to clients if your origin is offline.</html>"};


Note: Don’t forget that if you add custom vcl to your service, remember to include the boilerplate: Mixing & Matching Custom VCL with Fastly VCL

How Does vcl_error Work?

And if you want images/logos on this synthetic page, you can use Inline Images with Data URLs