Jartan-LLC 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
- Use the
{"code": "...", "reason": "..."}format - Reuse an existing code if the error is semantically identical
- Use
UPPER_SNAKE_CASEfor codes - Write reasons as complete sentences the frontend can show to users
- Use appropriate HTTP status codes per the table above