# Failures

Your code says what went wrong, by name, and Jadpo decides how each
failure reaches whoever called: the HTTP status, the response body and
what is logged. Code never throws, never picks an HTTP status and never
builds an error response.

Three kinds of thing can go wrong, and only the first is yours to
declare:

- A **domain failure** is an outcome your app expects, such as a todo
  that doesn't exist. You declare it and say where it can happen.
- A **fault** is a problem outside your code: the database is down, a
  provider timed out, or a write may or may not have been saved. The
  runtime raises it.
- A **defect** is a bug: a number overflowed, the recursion limit was
  reached, or the compiler got something wrong. The runtime raises it
  too.

| | Declared by | Listed in `fails` | The client sees | The log gets |
|---|---|---|---|---|
| **Domain failure**, such as `TodoNotFound` | you, as `type X = Failure` | yes | its code, message and client fields | its code, where it was raised, the path it travelled and its internal fields |
| **Fault**, such as the database being down | the runtime | no | a fixed code for that fault | the cause chain |
| **Defect**, such as an overflow | the runtime | no | `internal_fault` | the cause and stack |

| Page | What it covers |
|---|---|
| [Declaring a failure](/docs/declaring-a-failure.md) | A failure is a way an action or query can fail that its caller is expected to handle, such as stock running out. |
| [Failure kinds](/docs/failure-kinds.md) | Every failure has a kind, which decides the HTTP status a client gets and what the failure means. |
| [Saying what can fail: fails](/docs/saying-what-can-fail-fails.md) | A function or action lists the failures it can end with after `fails`, in its signature. |
| [Raising a failure: reject](/docs/raising-a-failure-reject.md) | `reject` ends the callable with a declared failure. |
| [Passing a failure on: attempt](/docs/passing-a-failure-on-attempt.md) | `attempt` passes every failure of a call on to your caller, so each one must be in your own `fails` list. |
| [Turning one failure into another](/docs/turning-one-failure-into-another.md) | A failure can come from something the compiler knows can go wrong, such as a read that finds nothing, a write that breaks a unique rule or a construction, or from another call. |
| [Handling a failure in match](/docs/handling-a-failure-in-match.md) | A `match` on a call handles its outcome: one arm for success, and one for each failure the call can produce (Match). |
| [What the client sees](/docs/what-the-client-sees.md) | Every failure reaches an HTTP client in the same envelope. |
| [Faults](/docs/faults.md) | A fault is raised by the runtime when something outside your code goes wrong. |
| [Concealing records](/docs/concealing-records.md) | When policy hides a record from a caller, saying "forbidden" would reveal that it exists. |
| [Logging](/docs/logging.md) ○ not built | Every failure and fault writes one structured event. |
| [Messages and languages](/docs/messages-and-languages.md) | A failure's `message` is fixed English for developers and logs. |

[What is built](/docs/failures-built.md) says which of this works today.