Handling Errors
1. Structuring Error Responses
Use RFC 7807 Problem Details (application/problem+json) as the cross-language standard.
| Field | Required | Purpose |
|---|
type | Recommended | URI identifying error type |
title | Yes | Short human-readable summary |
status | Yes | HTTP status code |
detail | Yes | Specific explanation |
instance | Optional | URI of failed request |
errors | Optional | Array of field-level errors |
traceId | Optional | Correlation ID for support |
2. Using Standard Error Codes
| Application Code | Maps To HTTP | Use |
|---|
VALIDATION_FAILED | 422 | Schema/business validation |
NOT_FOUND | 404 | Resource missing |
UNAUTHORIZED | 401 | Missing/expired token |
FORBIDDEN | 403 | Insufficient permissions |
CONFLICT | 409 | State conflict |
RATE_LIMITED | 429 | Quota exceeded |
INTERNAL_ERROR | 500 | Unhandled exception |
3. Including Field-Level Errors
Example: Field Errors Array
{
"title": "Validation Failed",
"status": 422,
"errors": [
{"field": "email", "code": "REQUIRED", "message": "Email is required"},
{"field": "age", "code": "OUT_OF_RANGE", "message": "Must be 18-120", "value": 15},
{"field": "items[0].sku", "code": "NOT_FOUND", "message": "SKU not found"}
]
}
4. Providing Error Messages
| Audience | Message Type |
|---|
| End user | Friendly, actionable, localized |
| Developer | Technical detail, machine-readable code |
| Logs only | Full stack trace, internal IDs |
5. Including Error Documentation Links
| Field | Example |
|---|
type (URI) | https://api.example.com/docs/errors/validation |
helpUrl | Custom field linking to docs/troubleshooting |
6. Handling Validation Errors
| Stage | Status | Body |
|---|
| Malformed JSON | 400 | Parse error position |
| Schema mismatch | 400 or 422 | Field paths + codes |
| Business rule | 422 | Rule code + explanation |
7. Handling Server Errors
| Status | Cause | Action |
|---|
| 500 | Unhandled exception | Log fully; return generic message |
| 502 | Bad upstream response | Retry or fail fast |
| 503 | Service unavailable | Include Retry-After |
| 504 | Upstream timeout | Increase timeout or fail |
8. Implementing Error Logging
| Log Field | Purpose |
|---|
| traceId / requestId | Correlation across services |
| userId / tenantId | Affected user/tenant |
| endpoint + method | Identify failing operation |
| statusCode + errorCode | Categorize for alerting |
| stack trace | Server-side only, never returned |
| duration | Performance correlation |
Warning: Never expose: stack traces, SQL queries, file paths, internal IPs, secret keys, password hashes, or PII in production error responses.
| Anti-Pattern | Risk |
|---|
| Stack trace in 500 body | Reveals framework, file paths |
| "User not found: alice@x.com" | Email enumeration |
| SQL error verbatim | SQL injection vector hint |
10. Providing Localized Error Messages
| Approach | Implementation |
|---|
| Server-side i18n | Resolve via Accept-Language + resource bundles |
| Code + client lookup | Return code; client maps to localized text |
| Hybrid | Code + default English message |
11. Including Stack Traces
| Environment | Stack Trace |
|---|
| Production | Never in response; log only |
| Staging | Optional under feature flag |
| Development | OK to include in body for debugging |