mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-15 21:46:29 +03:00
Magnus HedemarkandGitHub
c7c4d3b74f
Engineering: backend-engineering, frontend-engineering, data-engineering, ml-engineering, platform-engineering, qa-methodology Executive: go-to-market, legal-strategy, operational-design, org-design, product-strategy ml-engineering: added missing training-infrastructure.md reference qa-methodology: added test-data-management, performance-testing, security-testing references All frontmatter converted to agent-skills convention. Source: https://github.com/magnus919/hermes-profiles
47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# Error Handling
|
|
|
|
## Error Classification
|
|
|
|
| Category | HTTP analogue | What it means | Example |
|
|
|----------|--------------|---------------|---------|
|
|
| Validation | 400 | The client sent something wrong | Missing required field |
|
|
| AuthN/AuthZ | 401/403 | The caller can't do this | Expired token, insufficient permissions |
|
|
| Not Found | 404 | The resource doesn't exist | Invalid ID, deleted entity |
|
|
| Conflict | 409 | The operation can't complete due to state | Duplicate, stale version |
|
|
| Rate Limited | 429 | Too many requests | Quota exceeded |
|
|
| Internal | 500 | Something went wrong on the server | DB down, unhandled exception |
|
|
| Unavailable | 503 | The service can't handle the request right now | Circuit open, overloaded |
|
|
|
|
## Exception Handling Strategy
|
|
|
|
| Catch location | What to do | Example |
|
|
|---------------|------------|---------|
|
|
| Repository | Wrap DB errors in domain exceptions | `UserNotFoundException`, `DuplicateEmailError` |
|
|
| Service | Handle domain exceptions, orchestrate recovery | Retry on conflict, fallback on unavailable |
|
|
| Controller boundary | Map domain exceptions to error responses | `UserNotFoundException` → 404 with error body |
|
|
| Middleware boundary | Catch unhandled exceptions, log, return 500 | Global error handler, structured log + trace |
|
|
|
|
## Structured Logging Fields
|
|
|
|
Every log entry at service level should include:
|
|
|
|
- `request_id` — correlation ID from request header or generated at middleware
|
|
- `service` — service name
|
|
- `operation` — what operation was being performed
|
|
- `duration_ms` — how long it took
|
|
- `error_code` — if error, machine-readable code
|
|
- `caller` — function/module that produced the log
|
|
|
|
## Error Response Body
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "RATE_LIMITED",
|
|
"message": "Too many requests. Please retry after the specified time.",
|
|
"retry_after_seconds": 30,
|
|
"request_id": "req_abc123"
|
|
}
|
|
}
|
|
```
|