Integration stopped working and nothing on the customer side changed

Can I prove the route the customer is calling still exists?

The ticket

CUSTOMER TICKET: customer lookup returns not found for accounts that exist

Account: Copperline Robotics (growth) Impact: account lookups failing across their support tooling Started: noticed this morning

Our internal tool looks up customer records through your API and it has started saying not found for accounts we can see perfectly well in your web app. The account IDs are correct, I checked three of them by hand. We have not changed this integration since we built it last year.

Your job

1. Reproduce the failure before you accept the customer's framing.
2. Prove whether the record is missing or the request is.
3. Get the lookup succeeding, then write the update.

Working notes

The API is at http://127.0.0.1:8101. The customer's own request lives in labs/api/_stack/request.sh. Run it to reproduce, edit it until it succeeds, then run tse check. Credentials you have access to are listed in labs/api/_stack/credentials.md.

Track

APIs

Time

about 25 minutes

Difficulty

Straightforward

Tier

Core

Do these first: Integration rejected with an authentication error

Start it

In a Codespace or a local clone:

tse start api/03-integration-broke-after-upgrade

That provisions the broken system and prints the ticket above. Investigate with ordinary tools, then run tse check.

Look at the evidence

Real output, captured by running these commands against the broken system and checked against it on every build. It shows you what the evidence looks like. It cannot fix anything, and it will not tell you what is wrong.

Type a command you would reach for, or help.

CommandRun

Enter runs it. Shift and Enter start a new line. The up and down arrows walk back through what you have typed.

Show which commands are recorded (this is close to a hint)

Investigation scratchpad

Saved in this browser as you type. Nothing is uploaded. 0 of 7 filled in.

1. Customer symptom

In their words, not yours. Include scope and urgency.

2. Prediction

Before running anything: target layer, expected output, two likely causes.

3. Evidence gathered

The command or query, and why it is safe to run here.

4. Confirmed / disproven / still unknown

Three separate lists. This is the step people skip.

5. What it proves

One proof sentence, one safe next step, one alternate hypothesis.

6. Customer update and escalation note

Plain language. Impact first. No blame, no speculation.

7. Recall

One gap, one command to repeat tomorrow, one confidence score.

Copy as markdownClear

Hints

Each hint gives away a little more. Try to spend a few minutes on your own evidence first, because the recall is what makes it stick.

Hint 1 of 3

The customer has checked the account IDs by hand, and they are correct. Believe that, because it is cheap to verify and they clearly did the work.

So if the IDs are right and the records exist, "not found" is telling you something other than what the customer assumed. A 404 answers a question about an address, and there are two addresses in play: the record, and the route used to ask for it.

Reproduce the call and read what the response actually says is missing. The wording distinguishes the two.

Hint 2 of 3

The body says "code": "route_not_found", not something like record_not_found. The API never got as far as looking for the customer, because nothing serves that path.

That reframes the ticket completely. The data is fine. The address is stale.

Now, the customer says nothing changed on their side, and that is probably true. Something changed on ours. A well-behaved API does not withdraw a route silently, it announces it, and it announces it in the response headers rather than the body.

Re-run the request and read everything above the JSON.

Hint 3 of 3

Read the full response including headers:

curl -i http://127.0.0.1:8101/v1/customers/cus_8823

Two headers carry the answer:

Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: </v2>; rel="successor-version"

Sunset (RFC 8594) states when the resource stopped being served. Link with rel="successor-version" names what replaced it. The detail in the body says the same thing in prose.

Update the path in labs/api/_stack/request.sh to the current version, confirm you get the account record, then run tse check.

Worth noticing for the customer update: this integration has been broken since 1 August, and they only reported it this morning. Ask what else calls the old version.

Solution

Write your customer update before you read this. Comparing your wording against the model answer is worth more than reading it cold.

Reveal the solution

Solution: lookups return not found for accounts that exist

What the evidence proved

Evidence	What it proved	What it did not prove
HTTP 404	Something was not found	Whether it was the record or the route
"code": "route_not_found"	Nothing serves that path. The lookup never ran	Nothing about the account
Sunset: Sat, 01 Aug 2026	The route was withdrawn on a specific date
Link: </v2>; rel="successor-version"	What replaced it
Same ID against /v2 returns the record	The data was always fine

Root cause

The customer's tool calls /v1/customers/{id}. The v1 API was withdrawn on 1 August 2026 and the current API is served under /v2. Every lookup has failed since that date. The account records were never missing.

The customer said nothing changed on their side, which is true. The change was on ours, and their integration had no reason to notice until someone looked.

The distinction that decides the ticket

A 404 is an answer about an address, and there were two candidate addresses. Reading the error code rather than the status separated them immediately:

• record_not_found would mean the route worked and the account did not exist. That would be a data question.
• route_not_found means the request never reached account lookup at all. That is a routing and versioning question.

Everything after that follows from picking the right branch.

Read the headers

The most useful evidence here was not in the body:

curl -i http://127.0.0.1:8101/v1/customers/cus_8823

Sunset (RFC 8594) declares when a resource stops being served. Link with rel="successor-version" names the replacement. A deprecating API that sets these is telling you the answer directly, and most people never look, because the body is what gets printed in application logs.

Scoped fix

In labs/api/_stack/request.sh, call the current version:

curl ... "$API/v2/customers/cus_8823"

Then tse check.

Customer update

I reproduced the failure and the accounts are not missing. Your tool is calling version 1 of our API, which was withdrawn on 1 August, so those requests are being rejected before any account lookup happens. That is why the IDs look correct and still return not found. Pointing the integration at /v2 resolves it, and I have confirmed the same account IDs return correctly there. The response format for this endpoint is unchanged, so it should be a path change only.

One thing worth flagging: this has been failing since 1 August rather than since this morning, so it is worth checking whether anything else in your tooling still calls the older version. I am happy to review a list of the endpoints you use.

That closing offer is the difference between fixing a ticket and preventing the next four.

Engineering escalation, if you needed one

Not for the account. Possibly for the process:

Impact: enterprise customer integration failing silently for two weeks after the v1 withdrawal. Evidence: 404 route_not_found on /v1/customers/{id} with Sunset 2026-08-01; the same IDs resolve on /v2. Request: confirm whether v1 callers were identified and notified before the withdrawal date, and whether other accounts are still calling v1 today.

Check your understanding

Three questions on what the evidence here proved, and what it pointedly did not. Wrong answers explain themselves, and so do right ones.

tse quiz

Check your understanding

Three questions on what the evidence proved and what it did not. Every answer explains itself, including the right one.

Question 1 of 3A not-found answer comes back for a customer record. Why is that not yet a data question?

• It is an answer about an address, and there were two candidate addresses: the record, and the path used to ask for it.
• Answers of that kind are usually wrong.
• The customer may have sent an identifier that does not exist.
• The record was most likely deleted.

Question 2 of 3The response carried a withdrawal date and a pointer to what replaced it. What are those actually worth to the person answering the ticket?

• They establish that the customer should have read the changelog.
• They prove the record still exists.
• They turn the reply from "this stopped working" into a date, a reason, and the exact change to make.
• They allow the withdrawn path to be switched back on temporarily.

Question 3 of 3What is the general habit this exercise is arguing for?

• Retry a failed call before investigating it.
• Read the body of a failure, because the status is a category while the body is the specific claim.
• Reproduce every customer report before responding to it.
• Escalate anything that returns an unexpected status.

3 questions, none answered yet.

Why this one exists

A 404 on a route that used to work is a versioning event until proven otherwise, and a well-behaved API tells you so in its headers.

In an interview

Tests whether you read response headers at all. Most candidates read only the body, and the body here is much less informative than the Sunset and Link headers sitting directly above it.

Commands introduced

• curl -D
• Sunset header
• Link header

Evidence layers

• HTTP status code
• response headers
• deprecation signals