error
Available inrecvhitmisspassfetch
Triggers an error, creating a synthetic object and passing control to the vcl_error
subroutine.
error 602 "redirect-eu-edition";
The error
statement terminates the current subroutine. In all contexts except vcl_recv
, it transfers control to vcl_error
directly. If invoked in vcl_recv
, it will call vcl_hash
first, and then vcl_error
.
IMPORTANT: If there is an active response object, invoking error
will destroy it and create a new one. For example, if you invoke error
in vcl_fetch
, there will be an existing beresp
object representing the backend response, and when control passes to vcl_error
there will be an obj
that represents the new client response, but they are entirely different and do not inherit from each other.
The parameters for error
are the HTTP status code and status text to apply to the synthetic object which will be passed to the vcl_error
subroutine. From HTTP/2, the status text is no longer emitted on client responses, but can still be used as an internal signalling mechanism.
The status code and status text components are both optional. To specify the status text, the status code must also be specified. The following are all syntactically valid:
error;error 200;error 200 "OK";
If the code is not provided, it will default to 503
. If the status message is not specified, it will apply the default RFC text for the code or otherwise "Unknown Error".
Synthetic content
The synthetic
and synthetic.base64
statements in vcl_error
can be used in the event of an error condition, to generate a custom response at the edge, without fetching an object from cache or from a backend server. Thus it is common to trigger an error from anywhere in the VCL lifecycle by executing an error
statement with a custom status code, and then to catch that specific error in the vcl_error
subroutine so that a custom response can be composed and delivered:
if (obj.status == 601) { set obj.status = 200; set obj.http.Content-Type = "text/plain"; synthetic "Hello!"; return (deliver);}
Best practices for using status codes for errors
HTTP status codes are always three digits, so those below 100 and above 999 are not valid. Those between 100 and 599 are used or reserved by the HTTP specification, and above 700 some codes are reserved by Fastly. Ultimately, you should emit a response with a status code that a client will recognize. However, defining the ultimate status code at the point at which you call error
means it may be difficult to differentiate between errors triggered in different subroutines or for different causes. Additionally, vcl_error
may be called by Fastly if a network error occurs, in which case the object will have a 503
status code.
It's therefore a good idea to use a non-standard status code in the 600
-699
range at the point of calling error
, and to convert it into a standard code within the vcl_error
subroutine:
if (obj.status == 601) { set obj.status = 308; set obj.http.Location = "/"; return (deliver);}