Skilllibrary api-debugging

install

source · Clone the upstream repo

git clone https://github.com/merceralex397-collab/skilllibrary

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/merceralex397-collab/skilllibrary "$T" && mkdir -p ~/.claude/skills && cp -r "$T/09-backend-api-and-data/api-debugging" ~/.claude/skills/merceralex397-collab-skilllibrary-api-debugging && rm -rf "$T"

manifest: 09-backend-api-and-data/api-debugging/SKILL.md

source content

Purpose

Systematically diagnose API failures by triaging HTTP status codes, diffing expected vs actual request/response payloads, validating schemas, inspecting auth token flows, debugging CORS configuration, diagnosing timeouts, and reproducing issues with curl commands. Produce a root-cause analysis with a verified fix path.

When to use

An API endpoint returns an unexpected status code or response body.
A client receives CORS errors when calling the backend.
Authentication or authorisation tokens are rejected unexpectedly.
Request payloads pass client validation but fail server-side schema checks.
An endpoint times out intermittently or under specific conditions.
A webhook or callback is not being received by the target.

Do NOT use when

The issue is purely frontend rendering or CSS — no API involvement.
The task is to design a new API — use
```
api-contracts
```
for design work.
The problem is a database migration or schema evolution — use a data-model skill.
The endpoint works correctly but is slow — use a performance optimisation skill.

Operating procedure

Reproduce the failure: construct a minimal
```
curl
```
command that demonstrates the issue, including method, headers, auth token, and body. Run it and capture the full response with
```
curl -v -X <METHOD> -H 'Content-Type: application/json' -H 'Authorization: Bearer <token>' -d '<body>' <url> 2>&1
```
.
Triage by HTTP status code:
- 4xx: Read the response body for error details. Check request headers, auth token expiry, and payload shape.
- 5xx: Search server logs with
```
grep -i 'error\|exception\|traceback' <logfile> | tail -30
```
  or check
```
docker logs <container> --tail 50
```
  .
- Timeout/No response: Check if the service is running (
```
ss -tlnp | grep <port>
```
  ) and test connectivity (
```
curl -sS -o /dev/null -w '%{http_code}' http://localhost:<port>/health
```
  ).
Diff the expected vs actual response: compare the documented/expected response schema against the actual response using
```
diff <(echo '<expected>') <(echo '<actual>')
```
or a JSON diff tool.
Validate the request payload against the API schema: locate the schema definition (OpenAPI/Swagger file, Zod schema, Pydantic model, or JSON Schema) with
```
find . -name '*.yaml' -o -name '*.json' | xargs grep -l 'paths\|openapi\|schema'
```
and check each field.
Inspect auth flow: decode the JWT token with
```
echo '<token>' | cut -d. -f2 | base64 -d 2>/dev/null
```
and verify issuer, audience, expiry, and scopes match the endpoint requirements.
Debug CORS: check server CORS config by searching
```
grep -rn 'cors\|Access-Control' --include='*.{ts,js,py,go,yaml}' .
```
and verify allowed origins, methods, and headers match the client's request.
Check middleware chain: trace the request path through middleware by reading route definitions and middleware registration order — list each middleware and its effect.
Verify environment configuration: check that environment variables for the API (DATABASE_URL, API_KEY, SERVICE_URL) are set and not empty with
```
env | grep -iE 'database|api|service|redis|port'
```
.
Test the fix: after identifying the root cause, construct a corrected curl command or code change and verify the response matches expectations.
Document the root cause, the fix, and a regression test suggestion in the output format below.

Decision rules

Always reproduce with curl before reading code — the actual HTTP exchange is ground truth.
If the status code is 401/403, check auth before anything else — 90% of these are token issues.
If the response body is empty, check Content-Type headers and serialisation middleware.
If CORS fails, the fix is always server-side — never disable CORS on the client.
If logs show no evidence of the request arriving, the problem is routing, DNS, or network — not application code.
Prefer the simplest explanation: misconfigured env var > code bug > infrastructure issue.

Output requirements

Reproduction Command — exact curl command that demonstrates the failure.
Status Code Triage — what the code means in this context.
Request/Response Diff — side-by-side comparison of expected vs actual.
Root Cause — one-paragraph explanation with file paths and line numbers.
Fix — specific code change or configuration update with before/after.
Regression Test — suggested test case to prevent recurrence.
Related Endpoints — list any other endpoints likely affected by the same root cause.

References

OpenAPI/Swagger specs if present in the repo
Server framework documentation (Express, FastAPI, Gin, etc.)
Auth provider documentation (Auth0, Firebase Auth, Cognito, etc.)
MDN HTTP Status Code reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status

Related skills

```
api-contracts
```
— for API design and schema definition issues
```
shell-inspection
```
— for verifying service and environment state
```
security-review
```
— for auth-related vulnerabilities discovered during debugging
```
data-model
```
— for database-related API failures

Failure handling

If the API is not running locally, check for Docker containers or remote URLs and adjust reproduction commands accordingly.
If logs are inaccessible, note the gap and recommend log access setup, then proceed with black-box debugging from curl output alone.
If the auth token cannot be obtained (e.g., requires OAuth flow), document the auth prerequisites and test with a manually provided token.
If the root cause spans multiple services, document the cross-service interaction and identify which service owns the fix.