Error handling-related code must follow the specifications below.
Before Coding
First classify expected errors vs. unexpected errors, then write code.
Error Classification
- Expected errors (validation failures, resource not found) → handle normally, return friendly information
- Unexpected errors (system failures, third-party outages) → log them, return a generic error
- Do not wrap all code in try-catch—only catch what you can handle
Structured Errors
- Unified error format:
{ code, message, details? } - Accurate HTTP status codes: 4xx client errors, 5xx server errors
- Do not expose internal implementation details (stack traces, SQL, file paths) to users
- Error codes should be enumerable for easy frontend handling
Logging Specifications
- Structured logging (JSON), including timestamp, level, context
- Error logs include: stack trace, request ID, user context
- Redact sensitive information before logging (passwords, tokens, ID numbers)
- Log levels: error (must be handled) > warn (needs attention) > info (normal flow) > debug (debugging)
Recovery Strategies
- External calls: timeout + retry (exponential backoff, maximum 3 times)
- Critical operations: idempotent design, support safe retries
- Graceful degradation: partial feature unavailability does not affect core flows
- Circuit breaker: fail fast when consecutive failures exceed the threshold
Delivery Checklist
- Error response format is unified
- Do not expose internal details to users
- External calls have timeout settings
- Sensitive information has been redacted
- No silent failures: no empty catch swallowing errors, no silent degradation, no silent fallback (see HelloAGENTS "Failure Handling")