---
kind: guide
zz: "0.8.0"
updated: 2026-10-10
state: live
rules: https://zriz.io/llms.txt
---
# Test that a missing record returns 404

Ask for a record that does not exist in a zriz pipeline. The API must answer 404 with an error, not 500 and not 200 with an empty body.

## The problem {#problem}

A request for an unknown id shows how an API handles nothing. Some APIs answer `500`, because the code reads a field of a null record. Others answer `200` with an empty body, and the client breaks later.

## The test {#test}

The example is a shop API. `GET /api/orders/{order-id}` gives one order. The test asks for an id that no order has.

Start from a project that `zz init` made: the [quick start](https://zriz.io/docs.md) gives the commands. Add two actions to the resource file.

`.zriz/resources/target.json`:

```json
{
  "type": "http",
  "description": "Your app under test",
  "base-url": "${env.TARGET_URL}",
  "headers": { "Content-Type": "application/json" },
  "actions": {
    "check": { "method": "GET", "path": "/api/health" },
    "register": { "method": "POST", "path": "/api/auth/register" },
    "get-order": { "method": "GET", "path": "/api/orders/{order-id}" }
  }
}
```

`.zriz/pipelines/order-not-found.json`:

```json
{
  "description": "An unknown order id must get 404",
  "steps": [
    {
      "call": "target/register",
      "body": { "email": "u-${gen.uuid}@test.com", "password": "secret123", "name": "Ann" },
      "expect": [["status", "==", 201]],
      "save": { "token": "body.token" }
    },
    { "set": { "order-id": "${gen.uuid}" } },
    {
      "call": "target/get-order",
      "headers": { "Authorization": "Bearer ${ctx.token}" },
      "expect": [
        ["status", "==", 404],
        ["body.error", "==", "order not found"],
        ["body.order_id", "not-exists"]
      ]
    }
  ]
}
```

## Run it {#run}

```sh
zz run order-not-found
```

```text
"status":"pass"
```

## What it proves {#proves}

- `status == 404`: the API tells the client that the record is absent. A `500` or a `200` fails the test.
- `body.error == order not found`: the result names the fault.
- A valid token in the call: the `404` comes from the missing record, not from a refused login.

> Common mistake: A test with no token gets `401` and never reaches the code that looks for the record.

## Next {#next}

- [All lessons](https://zriz.io/learn.md)
- [Test an API status code and response body](https://zriz.io/learn/test-api-status-code-and-body.md)
- [Pipelines](https://zriz.io/docs/pipelines.md) lists each operator of a check.