Menu
API error response format -- machine-readable codes, human-readable reasons, status code rules.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
How agents, skills, and commands work in Claude Code projects.
GitHub conventions -- branch naming, commit format, issue/PR templates, and safe issue/PR referencing in comments.
Language-agnostic code hygiene -- honest comments, no dead/reinvented/duplicated code, truthful names, real implementations, and scoped (never blanket) diagnostic suppressions.
Language-agnostic structural craft -- decompose on responsibility not size, prefer deep modules over shallow piles, and shape cohesion, coupling, interfaces, error contracts, and data invariants. Sibling to code-hygiene and readable-code.
Documentation writing conventions -- style, structure, tone, and quality standards.
CSS design system principles -- token usage, semantic layering, mobile-first, component isolation.
| name | api-error-patterns |
| description | API error response format -- machine-readable codes, human-readable reasons, status code rules. |
| when_to_use | Writing API error handling, choosing HTTP status codes, designing error response shapes. |
All API error responses use a consistent format:
{
"detail": {
"code": "UPPER_SNAKE_CASE_CODE",
"reason": "Human-readable message."
}
}
code: Machine-readable identifier. Frontend uses this for branching logic (redirect to verification, show specific field errors).reason: User-facing message. Frontend can display directly. Always a complete sentence ending with a period.| Status | When to Use |
|---|---|
| 200 | Successful operation that returns data |
| 201 | Resource created |
| 204 | Success with no body (logout, delete, disable) |
| 400 | Client sent bad data (invalid input, bad credentials) |
| 403 | Authenticated but forbidden (wrong password, disabled feature, insufficient role) |
| 404 | Resource not found |
| 409 | Conflict (duplicate resource) |
| 429 | Too many requests (rate limit exceeded) |
| 500 | Unexpected server error (never intentional except for genuine internal failures) |
{"code": "...", "reason": "..."} formatUPPER_SNAKE_CASE for codes