# Errors

A handler or filter that gives `error(message)` makes a 500 with the body `Internal Server Error`. The message goes to stderr, never to the client. `Bond.bad_request(message)` is the error that makes a 400 with `message` as its body.

A runtime error in a handler or filter (an index out of range, an `unwrap!` of an error) is a 500 too, and does not stop the program: the request runs in a task of its own. The VM prints the stack trace on stderr, and Bond adds a line with the method and the path. The `after` filters do not run for a crash.

A response that the HTTP server of `std/http` would refuse is a plain 500, with a warning on stderr. That is a status outside 200 to 599, a `Content-Length` or `Transfer-Encoding` header, a header name that is not an HTTP token, and a value with a control character. A 204 or 304 loses its body. Over a socket the server checks the head in C before it writes a byte, so the answer is a 500 with no body that closes the connection (a `Location` that is not ASCII is the plain 500 of Bond, which keeps it); `Testing.request` has no server, so Bond checks the same rules there and gives the plain 500. Over a socket a header value may hold only printable ASCII and a tab today: a byte above 127 (`é`) is refused too, though the rule says Latin-1 ([agentica#1184](https://github.com/agentica-lang/agentica/issues/1184)).

## Custom handlers

The handlers are your code, so escape any value of the client that they put in HTML, `conn.path` included: see [HTML and escaping](https://agentica-lang.github.io/bond/guide/escaping/index.md). `Bond.not_found(app, handler)` answers a path with no route, in place of the plain `not found`. The handler is an ordinary `Bond.Handler`, called with the `Conn` with status 404, and the `after` filters run after it. It does not answer a 405, nor a 404 that a handler gives itself.

`Bond.on_error(app, handler)` answers a failure in place of the plain 500. The handler is a `Bond.ErrorHandler`, a `Fn[Bond.Conn, String, Result[Bond.Conn]]`: it takes the `Conn` and the message of the failure, and gives a `Result[Bond.Conn]`. It gets the request `Conn` with status 500 and nothing of the answer built so far. Bond has already written the message to stderr, and nothing sends it to the client unless the handler does: keep it out of the answer.

If the error handler gives an `error` or crashes, the answer is the plain 500. It is never called for a `bad_request`, nor for a response that the server would refuse. Both handlers are set once per app; a second call replaces the first.

```agentica
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"

def broken(conn: Bond.Conn) -> Result[Bond.Conn]
  return error("the database is down")
end

def page_not_found(conn: Bond.Conn) -> Result[Bond.Conn]
  return ok(Bond.html(conn, 404, "<h1>Nothing at #{Bond.escape(conn.path)}</h1>"))
end

def page_failed(conn: Bond.Conn, message: String) -> Result[Bond.Conn]
  return ok(Bond.html(conn, 500, "<h1>Something went wrong</h1>"))
end

def main() -> Void
  app = (
    Bond.app()
    |> Bond.get("/broken", &broken)
    |> Bond.not_found(&page_not_found)
    |> Bond.on_error(&page_failed)
  )
  missing = Testing.request(app, "GET", "/nothing")
  puts("#{missing.status} #{Testing.text(missing).unwrap!}")
  failed = Testing.request(app, "GET", "/broken")
  puts("#{failed.status} #{Testing.text(failed).unwrap!}")
end
```

```output
404 <h1>Nothing at /nothing</h1>
500 <h1>Something went wrong</h1>
```
