# Playbook: debug a failing call between services

**The question, in the user's words:** "The POST to `/api/shipments` from our main service is failing. Which code makes the call, which service is meant to answer it, and why does Niro think so?"

**What you get at the end:** the calling method, the service folder and method that handle the route, and what in the repository ties the address to that folder. Then, for a call that two services could answer, how to settle which one.

Words used on this page: a **route** is a web address a service answers, such as `POST /api/shipments`; a **handler** is the method that answers it; an **outbound call** is a call your code makes to another service's route.

## The steps

### 1. Find the call

```
niro ask find_outbound_http_calls path_pattern=/api/shipments

Found 2 outbound HTTP calls matching '/api/shipments'.
1. POST /api/shipments -> com.example.shop.shipping.ShippingMain.a_f_Ng3hlN
caller: ApacheHttpClient5Calls.createShipment
source: .../java-mono/main/src/main/java/com/example/shop/main/http/ApacheHttpClient5Calls.java
2. GET /api/shipments/{param} -> com.example.shop.shipping.ShippingMain.shipment_Np2ojN
caller: ApacheHttpClient5Calls.shipment
confidence: complete - this is the COMPLETE list.

```

Each line already says where the call lands. `a_f_...` is a function written in place: here a lambda, `(req, res) -> res.status(201).send()`.

### 2. Who answers it?

```
niro ask find_handler fqn=ApacheHttpClient5Calls.createShipment

Found 1 handler for 'ApacheHttpClient5Calls.createShipment'.
confidence: complete | has_more: false — this is the complete list.
1. ShippingMain.a_f [helidon-se]
source: services/helidon-se/src/main/java/com/example/shop/shipping/ShippingMain.java

```

### 3. Why that service?

The caller dials `http://shipping-api:8109/api/shipments`. Nothing in the Java code says that `shipping-api` is the `helidon-se` folder. The deploy file does:

```
# docker-compose.yml
shipping-api:
build: ./services/helidon-se
ports: ["8109:8109"]

```

Niro reads deploy files like this one to give each folder its address, then joins the call to the route. See [Configure a folder](https://help.niroai.dev/cli/configuring-a-folder/) to set an address by hand.

### 4. The whole map, when you do not know where to start

```
niro ask get_service_topology

18 link(s) between parts of this project:
main -> helidon-se  (2 route(s))
GET /api/shipments/{param}
POST /api/shipments
main -> javalin  (3 route(s))
GET /api/stock/{param}   (not confirmed)
...

```

### 5. When two services declare the same route

"(not confirmed)" means the call was matched by its path alone, and more than one service declares that path. The engine lists every such call and the command that settles it:

```
niro route-rule unconnected

1 call(s) joined only as candidates: more than one route could be meant ...
java-mono/main GET /api/stock/{param}: 2 services declare it (java-mono/services/javalin, java-mono/services/sparkjava)
niro-local route-rule add '/api/stock/{param}' --from java-mono/main --to java-mono/services/javalin
5 address(es) dialled that no service here answers on:
http://gift-cards-api:8113: 1 call(s) from java-mono/main; no service here declares their paths
...

```

Before the rule, `StockRetrofitApi.stock` was listed twice, once for each service, both "(one of several routes with this path, not confirmed)". After `niro route-rule add ...` and `niro build`, it is listed once, to the service named:

```
Before:  4. GET /api/stock/{param} -> ...stockspark.StockSparkApp.a_f_N657yN  (one of several routes with this path, not confirmed)
5. GET /api/stock/{param} -> ...stock.StockApp.a_f_Nes1yN  (one of several routes with this path, not confirmed)
After:   3. GET /api/stock/{param} -> com.example.shop.stock.StockApp.a_f_Nes1yN

```

**"No service here answers"** usually means the service lives in another repository that is not indexed, or its address is wrong. Check the address with `niro base-url` in the service's folder.

## Why the answer is deterministic

The link between a call and a handler comes from three things Niro read: the call's method and path, the route a framework declares, and the address of each folder. The same files always give the same links. Where the path alone matched and two routes fit, the answer says "not confirmed" and keeps it out of the risk counts, rather than guessing.

## What grep would do instead

- **grep finds the caller's URL string,** `http://shipping-api:8109/api/shipments`: the host name is in 3 lines, all in one file of main (two calls and a comment).

- **It does not find the handler by that string.** The handler file has only `"/api/shipments"` next to a lambda, and the host name `shipping-api` is in the compose file, not in any Java file of helidon-se. So the agent has to read the compose file and match the name itself. An agent using Niro can miss that line too, so when a call names a host, check the compose file as well.

- **It cannot tell which of two services answers `/api/stock/{id}`.** Both declare it; only an address or a rule settles it.

- **For routes declared by folder names it finds nothing.** In the TypeScript corpus, `GET /api/bookings/{param}` comes from the folder path `src/app/api/bookings/[bookingId]/route.ts`. `grep -rn "api/bookings"` finds 0 lines; `find_api_endpoints path_pattern=/api/bookings` finds 2 routes.

## Cost

What these steps cost depends on your code and your question. How Niro counts the size of its answers, and how to measure the cost on your own tasks, is in [Tokens, speed and accuracy](https://help.niroai.dev/cli/tokens-speed-and-accuracy/).

## Related

[Playbook: debug config and environment](https://help.niroai.dev/cli/playbook-debug-config/) (addresses that come from configuration), [Playbook: learn a new codebase](https://help.niroai.dev/cli/playbook-onboard/).