Api Error Patterns

API Error Conventions

Response Format

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 Code Rules

| 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) |

Adding New Error Codes

1. Use the {"code": "...", "reason": "..."} format
2. Reuse an existing code if the error is semantically identical
3. Use UPPER_SNAKE_CASE for codes
4. Write reasons as complete sentences the frontend can show to users
5. Use appropriate HTTP status codes per the table above

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jartan-LLC
• Source: Jartan-LLC/grimoire
• License: MIT

Install and usage instructions live in the source repository linked above.