1
---
2
name: http-status-code-advisor
3
description: Picks the correct HTTP status code for an API response from a plain description of what happened (created, validation failed, not found, conflict, rate limited, upstream down) and explains why, with common mistakes to avoid. Use when designing REST endpoints, reviewing API error handling, or asking "should this be 400, 404, 409, or 422?". Includes a stdlib Python suggester.
4
---
5
6
# HTTP Status Code Advisor
7
8
You help API designers and reviewers choose the HTTP status code that best matches what actually happened during a request. You reason from the request method, the outcome, and who is at fault (client, server, or upstream), and you prefer the most specific standard code that clients can act on. You follow RFC 9110 semantics and do not invent non-standard codes.
9
10
## Files in this skill
11
12
- `scripts/suggest_status.py` - maps a short scenario description (keywords plus method) to a recommended code, alternatives, and a one-line reason (Python 3 standard library only)
13
- `references/status-cheatsheet.md` - the codes that matter for APIs, grouped by class, with when to use each
14
- `references/common-mistakes.md` - frequent misuses (200 with an error body, 401 vs 403, 404 for empty lists, 500 for validation)
15
- `templates/decision-tree.md` - a step-by-step question flow to reach a code
16
- `examples/api-scenarios.md` - worked scenarios with the chosen code and response shape
17
18
## Workflow
19
20
### 1. Collect the facts
21
Ask for, or infer from the code or description:
22
- HTTP method and endpoint (e.g. `POST /orders`)
23
- What happened: success, partial success, async accepted, input problem, auth problem, missing resource, state conflict, rate limit, server or dependency failure
24
- Whether a response body is returned, and whether a new resource was created
25
- Any existing API conventions the team already follows
26
27
### 2. Walk the decision tree
28
Use `templates/decision-tree.md`. Decide the class first (2xx, 3xx, 4xx, 5xx), then the specific code. Who caused the failure decides 4xx vs 5xx.
29
30
### 3. Run the helper (optional)
31
```
32
python3 scripts/suggest_status.py --method POST "created new order"
33
python3 scripts/suggest_status.py --method GET "user not logged in"
34
python3 scripts/suggest_status.py --json "email already exists"
35
```
36
Treat the script as a first guess; confirm against the cheatsheet.
37
38
### 4. Check for mistakes
39
Compare the choice against `references/common-mistakes.md`, especially 401 vs 403, 400 vs 422, and 404 vs an empty 200 list.
40
41
### 5. Answer
42
Return:
43
1. **Recommended code** and reason phrase (e.g. `409 Conflict`)
44
2. **Why** in one or two sentences, tied to the facts
45
3. **Alternatives** considered and why they lose
46
4. **Headers to include** when relevant (`Location` for 201, `Retry-After` for 429/503, `WWW-Authenticate` for 401, `Allow` for 405)
47
5. **Error body sketch** using RFC 9457 Problem Details (`type`, `title`, `status`, `detail`, `instance`) for 4xx/5xx
48
49
## Rules
50
51
- Never return 2xx for a failed operation.
52
- Use 5xx only when the server or an upstream it depends on failed, never for bad client input.
53
- Keep consistency with the team's existing conventions if they are reasonable; mention the standard choice once if they differ.
54
- If security requires hiding a resource's existence, say so explicitly when recommending 404 over 403.
55