HTTP status codes and Fastly

HTTP requests have a response status code that indicates, primarily, whether the request was successful or not and provides additional information to help browsers and other clients to figure out what kind of response they got and how to react to it.

100-599: Standards range

All status codes lower than 600 are reserved by RFC 7231 and managed in the IANA http status codes registry. It's appropriate to use these to create responses to client requests, where the status is appropriate to the response. For example, the most common status for responses emitted by Fastly is 200 (OK).

If a network error occurs while processing a request (e.g., a backend timeout), Fastly will create an object with a 503 status and trigger the vcl_error subroutine instead of vcl_fetch. In such cases, information about the specific error may be available in obj.response or fastly.error.

For historical reasons, any object that triggers vcl_error with a 550 status will be caught by Fastly's #FASTLY ERROR macro and delivered unmodified.

600-699: Available for customer use

The range 600-699 is reserved for customer use and will never be defined or reserved by Fastly. When writing custom VCL, use codes in this range to throw explicit errors to be caught in vcl_error (typically, changing the status code back to one of the registered codes in the 100-599 range):

sub vcl_recv {
if (req.url.path == "/health") {
error 600;
}
}
sub vcl_error {
if (obj.status == 600) {
set obj.status = 200;
set obj.http.content-type = "text/plain";
synthetic "OK";
return(deliver);
}
}

700-899: Reserved for Fastly

Status codes in this range are used in the implementation of Fastly platform features or for signalling when transferring requests between Fastly cache servers or data centers.

WARNING: Constructing responses or triggering errors with a status in the 700-899 range may result in unpredictable or unexpected behavior.

Some customer-visible effects caused by status codes in this range to be aware of:

  • Any object that triggers vcl_error with an 801 status will prompt a redirect to the HTTPS version of the current request URL. This is part of our 'Force TLS' feature but the handler is rendered as part of the #FASTLY ERROR macro regardless of whether the feature is enabled.
  • Exiting vcl_fetch with a 701 status will trigger an internal restart.

Many other status codes in this range are used by Fastly in ways that are not visible to customers. We may, in the future, use other statuses in the 700-899 range for any purpose. We may also change or remove any of the existing behavior at any time and without notice. It's therefore highly inadvisable to either invoke or trap errors with status codes in this range.

900-999: Response object codes

Creating a response object using the API (or creating a response in the web interface) will generate VCL into the #FASTLY RECV and #FASTLY ERROR macros. In the former case, this is done to detect eligible requests and trigger an error. In the latter case, this is done to trap that error and deliver the desired response content (just as illustrated in the custom VCL example above, but generated automatically by Fastly).

Response objects use status codes starting from 900 to signal from the vcl_recv subroutine to the vcl_error subroutine. Each additional Response object created will use the next available status code in the 9xx range.

If you have created a Response object and know the status code Fastly has allocated to it, you can invoke that response in custom VCL using an explicit error statement, but be aware that if you delete a Response object defined earlier, later responses will be renumbered, potentially leaving your code referring to the incorrect response. In general, responses created using the API or web interface should only be invoked using other mechanisms available via the API or web interface, to ensure that references are correctly maintained.