1. Home
  2. Reference documentation
  3. VCL reference
  4. Statements

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.

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:

sub vcl_error { ... }
Fastly VCL
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:

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