---
name: api-route-debugger
description: "Finds why a single API route returns the wrong status or error, with an ordered checklist, the exact command to confirm each suspect, and a code patch for the most likely cause. Use when a specific API route returns the wrong status code or an unexpected error and the cause is not obvious from the logs. Do not use for writing a new route from scratch, or reviewing a route that works for style and test coverage. Related topics: coding, api."
---

# API Route Debugger

Finds why a single API route returns the wrong status or error, with an ordered checklist, the exact command to confirm each suspect, and a code patch for the most likely cause.

## When to use

Use this skill when a specific API route returns the wrong status code or an unexpected error and the cause is not obvious from the logs. Do not use it for writing a new route from scratch, or reviewing a route that works for style and test coverage.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Classify the failure by status code and error text into a layer (routing, middleware, auth, validation, handler, dependency) so the search starts in the right place.
3. Write a checklist ordered from cheapest to most expensive to confirm, each item paired with one command or request and the result that rules it in or out.
4. Read the handler and middleware against the sample payload and name the most likely root cause with the lines that support it.
5. Write the patch as a fenced code block in the framework's idiom, changing only what the diagnosis requires.
6. State the exact request to re-run and the response that confirms the route is fixed.

## Inputs

- **HTTP method** (choose one: GET, POST, PUT, PATCH, DELETE)
- **Route path** (free text, e.g. "/api/v1/orders/:id")
- **Expected status code** (free text, e.g. "200")
- **Observed status code and error message** (longer free text)
- **Sample request payload** (longer free text)
- **Authentication type** (choose one: None, API key, OAuth2, JWT, Session cookie)
- **Framework** (choose one: Express, FastAPI, Django, Spring, NestJS, Rails, Laravel, Other)
- **Route handler code** (longer free text)

## Output

A Markdown report with sections Overview, Environment, Checklist (ordered, each item with a verification command), Root Cause, and Suggested Fix with a fenced code block and the confirming request.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### API Route Debugger

Diagnose one failing API route and get it back to the expected response.

- HTTP method: {{HTTP method}}
- Route path: {{Route path}}
- Expected status code: {{Expected status code}}
- Observed status code and error message: {{Observed status code and error message}}
- Sample request payload: {{Sample request payload}}
- Authentication type: {{Authentication type}}
- Framework: {{Framework}}
- Route handler code: {{Route handler code}}

Read the error and the handler before guessing: the status code narrows the layer (4xx is routing, auth, or validation; 5xx is the handler or a dependency). Build a checklist ordered from cheapest to confirm to most expensive: route registration and method, middleware order, auth header parsing, body parsing and validation, then database or downstream calls. For each item give the single command or request that proves or rules it out (a curl call, a log grep, a one-line script) and what a passing result looks like. Name the most likely root cause with the evidence that points to it, then give a patch in a fenced code block in the framework's idiom, and the request to re-run to confirm the fix. If two causes remain equally likely, say so and give the check that splits them.

## Pitfalls

- Starting with the handler body when the status code says the request never reached it, such as a 404 from a route registered after a catch-all.
- Proposing a fix without a verification step, so the user cannot tell a real fix from a coincidental pass.
- Ignoring middleware order; a body parser mounted after the route leaves req.body empty and looks like a validation bug.
