## TL;DR

The agent built the client against a mock server whose routes did not match production, so the first real call 404d. Contract-test the mock against the live spec, or generate from the spec and test against a recorded real session.

## Error

```text
404 on the first production call for a route the mock served fine
```

## Steps

1. Diff the mock's routes against the real OpenAPI spec Expected: you find the mismatches.
2. Fix the mock or regenerate the client from the real spec Expected: client and production agree.
3. Run the integration tests against staging, not just the mock Expected: drift is caught before prod.
4. Record a real session and replay it in CI Expected: the mock stays honest.

## When to use

- Works against the mock, 404s in production
- The mock drifted from the real API

## When not to use

- Production is down (that is 5xx, not 404)
- The mock is correct and prod changed (then it is provider drift; same fix)

## Tool compatibility

- Mock fidelity
- Contract testing

## Variant phrasings

### mock vs production 404

Your mock drifted. Diff it against the real spec.

### works on mock fails on prod

Same: the mock's routes do not match production.

## Why it happens

Mocks are written once from the docs and never updated. Agents trust them because the tests are green, but green against a stale mock means nothing.

## Edge cases

- Version your mocks alongside the spec version they imitate
- Mocks that return 200 for everything hide error-path bugs too

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_zwt0h7cZybksKzhXpHHaGQ