Build decisions after:
Error 404 (Not Found)!!1

The demo worked because the endpoint existed. In production, the agent hits a 404 and the error propagates silently into the next step. You are now debugging a ghost that never actually executed. The engineer on call spends three hours tracing a logic error that is actually a missing ID. The data looks fine in the UI, but the backend is full of orphaned records.

You must decide if the team builds a specific handler for missing resources or defers write access until the agent proves it can distinguish a 404 from a success. This is not a feature request. It is a prerequisite for any system that modifies data. If you skip this, you are not building an agent; you are building a data corruption engine with a polite interface.

The desired outcome is a system that stops when a resource is missing. The actual outcome is often a retry loop that hammers the API or a false success that logs a null value. The gap between these two states is where your incident budget goes.

What breaks when the resource is missing

The failure mode is "optimistic null handling." The agent treats a missing object as an empty object. It then attempts to update fields on that empty object. The write succeeds technically but corrupts the data model.

This manifests in five specific ways. First, retry storms: the agent retries the GET request five times on a 404, exhausting rate limits. Second, null pointer writes: the agent updates a non-existent record, creating orphaned data entries. Third, context pollution: the 404 error message is fed back into the prompt, confusing the next reasoning step. Fourth, silent drop: the agent ignores the 404 and proceeds to the next task, skipping critical validation. Fifth, log noise: the 404 is logged as a warning, burying real errors in the noise.

Each of these has a cost. Retry storms trigger cloud bills. Orphaned data requires manual cleanup. Context pollution leads to hallucinated actions. Silent drops mean the job fails without anyone knowing. Log noise means you miss the real bug hiding in the warning stream.

Why you should defer write access

You should not grant write access until the agent proves it can handle a 404. This is the core build decision. The proof is a read-only shadow phase.

In this phase, the agent runs against production data but cannot write. It logs every 404 it encounters. You review these logs to see if the agent handles missing data gracefully. If it does, you allow writes. If it does not, you fix the handler.

This proves the agent understands the data schema before it touches it. It shifts the risk from "will it corrupt data" to "will it stop correctly." The latter is a solvable engineering problem. The former is a business risk.

How to design the read-only shadow phase

The control model is a strict "read-only shadow" phase. The agent runs against production data but cannot write. It logs every 404 it encounters. You review these logs to see if the agent handles missing data gracefully.

The mechanism is simple. The agent makes a GET request. If the response is 404, it logs the event with the run_id, the resource ID, and the timestamp. It does not retry. It does not assume an empty object. It halts the current task and returns a graceful null to the caller.

This log becomes your proof. You search for the pattern status: 404 in the logs. If you see it, you check the next step in the trace. Did the agent stop? Did it alert? Or did it proceed with a null value? If it proceeded, the shadow phase failed. You fix the handler and re-run.

When to halt versus when to retry

Not all errors are equal. A 500 error might be transient. A 404 is not. The resource does not exist. Retrying it will not make it exist.

The rule is: 404 is a hard halt. 500 is a soft retry. You encode this in the agent's error handling logic. The agent checks the status code. If it is 404, it stops. If it is 500, it retries up to three times with exponential backoff.

This distinction is critical. If you retry a 404, you are wasting API calls and increasing latency. If you halt on a 500, you are failing a task that might have succeeded. The agent must distinguish between "the thing is gone" and "the server is busy."

What the logs must show to prove safety

The logs must show three things. First, the 404 event. Second, the halt. Third, the alert.

The 404 event should include the resource ID, the run_id, and the timestamp. The halt should be a state change in the agent's execution trace. The alert should be a notification to the on-call engineer.

If any of these are missing, the system is not safe. If the 404 is logged but the agent continues, you have a silent drop. If the agent halts but no alert is sent, you have a silent failure. If the alert is sent but the 404 is not logged, you have a log gap.

You need all three to prove the agent is safe. The logs are your evidence. Without them, you are guessing.

How to measure the cost of a missed 404

The cost of a missed 404 is not just the incident. It is the time to detect it, the time to fix it, and the time to clean up the data.

A missed 404 can take hours to detect. The data looks fine in the UI, but the backend is full of orphaned records. The engineer spends time tracing the logic error. The fix requires a manual data cleanup script. The cleanup script takes hours to write and test.

The total cost is high. It is not just the labor hours. It is the trust erosion. Every incident makes the team less likely to adopt the agent. Every incident makes the business less likely to invest in the project.

The cost of a missed 404 is a business cost, not just a technical cost.

Why this method works for complex data models

The method works because it forces the agent to understand the data schema. It cannot assume an object exists. It must check. It must handle the case where it does not.

This is a fundamental principle of robust software. You cannot assume the input is valid. You must validate it. The agent is no different. It must validate the existence of the resource before it acts on it.

The method is scalable. It works for simple CRUD operations. It works for complex data models with relationships. It works for any system where the agent modifies data.

The key is the shadow phase. It allows you to test the agent in production without the risk of data corruption. It is a safe way to learn how the agent behaves in the real world.

Diagnose, Model, Build, Harden

The practitioner method is Diagnose, Model, Build, Harden.

Diagnose: Look at the current system. Where are the 404s? How are they handled? What is the cost of a missed 404?

Model: Design the read-only shadow phase. Define the logs. Define the halt condition. Define the alert.

Build: Implement the shadow phase. Run the agent in production. Collect the logs.

Harden: Review the logs. Fix the handler. Re-run the shadow phase. Repeat until the agent handles 404s correctly.

This method is iterative. It is not a one-time fix. It is a continuous process of improvement.

What to do this week

Run a read-only shadow phase for one week. Log every 404. Review the logs. Fix the handler. Re-run the shadow phase.

This is the concrete proof you need. It is not a feature request. It is a prerequisite. It is the difference between a system that works and a system that corrupts data.

Do it now. The cost of waiting is the first real incident.