error

errorINTEGERstatusSTRINGresponse;

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.

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. So these 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".

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 recognise. 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:

sub vcl_error { ... }
Fastly VCL
if (obj.status == 601) {
set obj.status = 308;
set obj.http.Location = "/";
return (deliver);
}