Template: Error Handling Strategy Document

Purpose

To define a consistent error handling strategy across services, ensuring predictable responses, easier debugging, and better user experience.

Scope

• Applies to all backend services (APIs, microservices, serverless).
• Used by Backend Developers, QA, Frontend Developers, and DevOps.
• Covers error classification, format, codes, retry logic, and logging standards.

Structure

Section 1 – Error Classification

Category	Description	Example (SaaS)	Example (B2C)
Validation Errors	Invalid input or missing fields	Email format invalid	Booking date missing
Authentication/Authorization	Identity or role issues	Invalid JWT token	User not logged in
Business Logic Errors	Domain-specific failures	User already onboarded	Cleaner not available
Resource Errors	Missing entities or duplicates	User not found	Booking not found
System Errors	Infra or dependency failure	DB connection timeout	Payment gateway down
Rate Limits	Too many requests	429 Too Many Requests	App spamming API

Section 2 – Error Format (REST & GraphQL)

Aspect	REST Example	GraphQL Example
Envelope	{ "error": { "code": 400, "message": "Invalid email" } }	{ "errors": [ { "message": "Invalid email", "path": ["createUser"] } ] }
Fields	code, message, details, traceId	message, path, extensions.code
Traceability	Include traceId in all errors	Extensions field for trace IDs

Section 3 – Error Codes

Code	Category	Description	Example
200	Success	Request processed successfully	GET /users
400	Validation Error	Invalid/missing input	Wrong email format
401	Unauthorized	Missing/invalid token	Expired JWT
403	Forbidden	User lacks permission	Non-admin updating roles
404	Not Found	Entity doesn’t exist	Booking ID invalid
409	Conflict	Duplicate or state conflict	Email already in use
429	Rate Limit	Too many requests	Throttled client
500	Server Error	Unexpected failure	DB crash
502/503	Dependency Error	Downstream service unavailable	Stripe API down

Section 4 – Retry & Recovery Guidelines

Error Category	Should Retry?	Client Action	Server Action
Validation	❌	Fix input	N/A
Auth	❌	Refresh token / login	N/A
Business Logic	❌	Adjust request	Log & notify
System (5xx)	✅ (with backoff)	Retry with exponential backoff	Circuit breaker / fallback
Rate Limit (429)	✅ (after wait)	Respect Retry-After header	Include rate-limit headers

Section 5 – Logging & Monitoring

Requirement	Standard
Log Level	WARN for client errors, ERROR for server failures
Context	Include traceId, userId (if available), requestId
Storage	Centralized log collector (e.g., ELK, Datadog)
Alerts	Trigger alerts on repeated 5xx or spikes in 4xx
Redaction	Strip sensitive data (PII, tokens) before logging

Section 6 – User Messaging (Frontend Integration)

Category	Developer-Facing Message	User-Facing Message
Validation Error	"Invalid email format"	“Please enter a valid email.”
Auth Error	"Expired JWT"	“Your session expired. Please log in again.”
System Error	"DB timeout on query X"	“Something went wrong. Try again later.”

Blank Reusable Template

Error Classification

| Category | Description | Example |

Error Format

| Aspect | Contract |

Error Codes

| Code | Category | Description | Example |

Retry & Recovery

| Error Category | Should Retry? | Client Action | Server Action |

Logging & Monitoring

| Requirement | Standard |

User Messaging

| Category | Developer-Facing Message | User-Facing Message |