---
title: error
summary: null
url: https://www.fastly.com/documentation/reference/vcl/statements/error
---

```
error(INTEGER status?, STRING response?);
```

**Available in:** recv, hit, miss, pass, fetch

Triggers an error, creating a synthetic object and passing control to the `vcl_error` subroutine.

```vcl
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](https://www.fastly.com/documentation/reference/http/http-statuses/) 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:

```vcl
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](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) 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](https://www.fastly.com/documentation/guides/full-site-delivery/custom-vcl/developer-guide-using) 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:

```vcl context="sub vcl_error { ... }"
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](https://www.fastly.com/documentation/reference/http/http-statuses/) 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](https://www.fastly.com/documentation/reference/http/http-statuses/#700-899-reserved-for-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:

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