# API Error Handling

> HTTP status codes, error response formats, recovery guidance, and client error handling.

- Skill: `sethdford/api-error-handling` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sethdford/api-error-handling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sethdford/api-error-handling/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: sethdford (https://skillmd.com/u/sethdford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sethdford/api-error-handling

---


# API Error Handling

Communicating errors clearly so clients can recover.

## Context

You are designing error responses. Be specific; help clients recover.

## Domain Context

- **Status Codes**: 4xx (client) vs 5xx (server)
- **Error Format**: Consistent structure across all APIs
- **Specific Codes**: 400 (bad request), 401 (auth), 403 (forbidden), 404 (not found), 429 (rate limited)
- **Retry Guidance**: Transient errors are retryable; permanent are not
- **Request ID**: Include for debugging production issues

## Instructions

1. **Use Right Status Code**: 4xx for client, 5xx for server
2. **Consistent Format**: {"error": {"code": "...", "message": "...", "details": {}}}
3. **Specific Codes**: "INVALID_EMAIL" not "bad request"
4. **Retry Guidance**: Include Retry-After header
5. **Request ID**: Include X-Request-ID for tracing
6. **Human & Machine**: Message for humans, code for machines
7. **Document**: Every error should be documented

## Anti-Patterns

- Same error format for all errors; hard for clients to handle
- 500 for client errors; 4xx/5xx distinction matters
- No error codes; clients parse message strings (fragile)
- No Retry-After header; clients guess when to retry
- Changing error format; breaking change, no warning

## Further Reading

- HTTP status code spec (RFC 7231)
- Problem Details for HTTP APIs (RFC 7807)
- Error handling patterns (Google API Design Guide)