后端接口错误处理全流程审计
追踪后端故障传播、错误映射与重试恢复路径,形成可转化为测试和修复任务的审计报告。
完整提示词
I want you to perform an ultra-deep, systematic, evidence-first, and production-oriented analysis of the complete error handling system across the backend/API application.
Main goal:
> Determine whether the backend properly detects, classifies, maps, logs, returns to clients, and recovers from errors without data loss, false successes, infinite retries, internal implementation leakage, or misinterpreting expected business rejections as systemic crashes.
This is not:
- generic advice to use `try/catch`
- a status code checklist
- just a logging audit
- just an observability audit
- just a security audit
- automatic conversion of all errors into custom exception classes
- an attempt to return the exact same response for every failure
- automatic retrying of all errors
- automatic concealment of all details regardless of debugging necessities
Focus is on the complete failure lifecycle:
```text
failure occurs
↓
exception/result created
↓
propagation
↓
classification
↓
mapping
↓
logging/metrics
↓
client response
↓
retry/recovery
```
Priority:
**correctness > data integrity > retry safety > error classification > client semantics > observability > developer ergonomics**
It is better to find 6 real failure path issues than to write 100 generic exception handling recommendations.
---
# 1. DETERMINE ERROR HANDLING STACK
Before findings, establish:
- framework
- exception middleware/filter
- validation library
- ORM/database layer
- HTTP client
- queue/job framework
- logger
- tracing
- metrics
- error monitoring
- external API integrations
Search for:
```text
try
catch
throw
Promise.catch
Result
Either
error middleware
exception filter
onError
retry
fallback
```
adapted to the project language and runtime.
---
# 2. MAP ERROR ARCHITECTURE
Map the actual error flow.
Example:
```text
Repository error
↓
Service
↓
Controller
↓
Global exception handler
↓
HTTP response
```
For background jobs:
```text
Worker failure
↓
queue retry
↓
dead letter / failed state
```
For external integrations:
```text
provider error
↓
adapter
↓
domain mapping
↓
API
```
---
# 3. ERROR INVENTORY
Classify failures into at least:
```text
VALIDATION
AUTHENTICATION
AUTHORIZATION
NOT_FOUND
CONFLICT
BUSINESS_RULE
RATE_LIMIT
TIMEOUT
DEPENDENCY
DATABASE
INTERNAL
CANCELLATION
```
Add domain-specific categories where present.
---
# 4. EXPECTED VS UNEXPECTED
The most critical distinction:
```text
EXPECTED FAILURE
```
examples:
- invalid input
- insufficient balance
- duplicate email
- invalid state transition
versus:
```text
UNEXPECTED FAILURE
```
examples:
- null dereference
- DB outage
- serializer bug
Never treat them identically.
---
# 5. DOMAIN ERROR
Expected business rejections must not automatically culminate in 500 errors.
---
# 6. SYSTEM ERROR
Unexpected internal exceptions must not be masked as:
```text
400 Bad Request
```
merely so the API "avoids returning 500".
---
# 7. ERROR PROPAGATION
For each critical flow trace where errors are:
- thrown
- caught
- wrapped
- transformed
- ignored
---
# 8. SWALLOWED ERROR
High-signal pattern:
```text
try {
importantOperation()
} catch {
}
```
If failure alters the business outcome, silently swallowing errors is a critical problem.
---
# 9. LOG-AND-SWALLOW
Pattern:
```text
catch (e) {
logger.error(e)
}
```
is insufficient if the caller continues execution assuming the operation succeeded.
---
# 10. FALSE SUCCESS
Scenario:
```text
DB write fails
↓
error caught
↓
function returns success object
↓
API returns 200
```
Severity P1/P0 depending on data and business impact.
---
# 11. ERROR TO NULL
Pattern:
```text
catch {
return null
}
```
Verify whether callers can distinguish:
```text
not found
```
from:
```text
database failed
```
---
# 12. DEFAULT VALUE ON ERROR
Pattern:
```text
catch {
return []
}
```
can convert a severe service outage into an apparent "no data available" state.
---
# 13. FALSE EMPTY STATE
Scenario:
```text
DB/API fails
↓
[]
↓
client displays "No results"
```
The user receives false negative information.
---
# 14. ERROR WRAPPING
When lower-level errors are wrapped in custom exceptions:
ensure critical context is not stripped.
---
# 15. ERROR CAUSE
If runtime supports exception causes or chaining:
verify the root cause remains accessible for internal debugging.
---
# 16. OVER-WRAPPING
Do not build 8 layers of custom exceptions that add zero semantic value.
---
# 17. ERROR TYPE AS CONTROL FLOW
Expected domain rejections can legitimately leverage typed error results.
Do not dogmatically insist on an exception-free model.
---
# 18. STRING MATCHING
High-risk pattern:
```text
if (error.message.includes("duplicate"))
```
for business or error classification.
---
# 19. DATABASE ERROR MAPPING
Map:
- unique violations
- foreign key violations
- deadlocks
- serialization failures
- connection losses
- timeouts
---
# 20. UNIQUE VIOLATION
Database duplicate constraints can map to:
```text
409 Conflict
```
or domain errors.
Verify it does not emit a generic 500 when duplicate submission is an anticipated business scenario.
---
# 21. UNIQUE CONSTRAINT IDENTITY
Never map every unique constraint violation to:
```text
EMAIL_ALREADY_EXISTS
```
if the underlying table maintains multiple unique constraints.
---
# 22. FOREIGN KEY FAILURE
Can represent:
- parent record missing
- invalid request payload
- race condition
- internal bug
Mapping depends on operational context.
---
# 23. DEADLOCK
Database deadlocks can be retryable at the transaction boundary.
Only safe if the entire operation can be cleanly re-executed.
---
# 24. SERIALIZATION FAILURE
Same applies for serializable transaction conflict retries.
---
# 25. DATABASE UNAVAILABLE
Do not translate into 404 or validation rejections.
This is a dependency/system failure.
---
# 26. POOL EXHAUSTION
Must generate observability alerts and 5xx responses, never business errors.
---
# 27. ORM ERROR
ORMs wrap native database errors.
Verify mappers rely on stable error codes or types rather than fragile error message strings.
---
# 28. EXTERNAL HTTP ERRORS
For each external provider map:
- timeouts
- DNS/connect errors
- 4xx responses
- 429 rate limits
- 5xx outages
- malformed responses
---
# 29. UPSTREAM 4XX
Never pass upstream provider status codes through to clients automatically.
Example:
```text
provider 401
```
does not mean our caller is unauthorized.
It usually indicates our internal provider credentials failed.
---
# 30. UPSTREAM 404
Does not equate to our resource being 404.
---
# 31. UPSTREAM 429
May demand:
- exponential retry
- queue buffering
- 503 or 429 passed to our caller
depending on architecture.
---
# 32. UPSTREAM 5XX
Classify strictly as dependency failure.
---
# 33. BAD PROVIDER PAYLOAD
An HTTP 200 response containing malformed JSON or schema violations is a failure.
Never treat HTTP status 200 as proof of successful execution.
---
# 34. RESPONSE VALIDATION
For critical integrations verify that incoming payloads satisfy required fields and types.
---
# 35. PROVIDER ERROR LEAK
Never echo raw Stripe, AWS, or third-party error objects to clients if that leaks:
- implementation internals
- resource identifiers
- request parameters
- secrets
---
# 36. PROVIDER ERROR TRANSLATION
Translate external errors into stable internal domain errors where appropriate.
---
# 37. TIMEOUT
Verify bounded timeouts exist for every downstream call.
---
# 38. NO TIMEOUT
External dependencies that can hang indefinitely will exhaust server connection pools and worker threads.
---
# 39. TIMEOUT CLASSIFICATION
A timeout is not equivalent to:
```text
operation definitely failed
```
especially during state mutations.
---
# 40. UNKNOWN OUTCOME
Critical scenario:
```text
request sent to payment/provider
↓
timeout
```
The provider may have successfully executed the side effect.
Retry strategies must account for this ambiguity.
---
# 41. CONNECTION RESET
Connection drops after dispatching requests similarly create unknown outcome states.
---
# 42. RETRYABILITY
For every error type classify:
```text
RETRY NOW
RETRY LATER
DO NOT RETRY
REAUTH
USER ACTION REQUIRED
UNKNOWN
```
---
# 43. RETRY MATRIX
| Error | Retryable | Safe automatically | Backoff | Max attempts |
|---|---|---|---|---|
---
# 44. RETRY VALIDATION ERROR
Retrying identical invalid payloads infinitely is a bug.
---
# 45. RETRY AUTH ERROR
401 responses require token refresh or re-authentication, not generic network retries.
---
# 46. RETRY 403
Permission failures do not resolve spontaneously upon retry.
---
# 47. RETRY 404
Depends on eventual consistency windows and operation semantics.
Do not over-generalize.
---
# 48. RETRY 409
Conflicts typically necessitate re-reading state or running reconciliation.
---
# 49. RETRY 429
Honor provider and server retry hints where provided.
---
# 50. RETRY 5XX
Bounded retries with backoff can be legitimate.
---
# 51. JITTER
For large-scale distributed clients or workers incorporate randomized jitter to prevent thundering herd stampedes.
---
# 52. NESTED RETRIES
Map layered retry cascades:
```text
API layer retry
↓
service retry
↓
HTTP client retry
↓
queue retry
```
Total retry attempts can multiply exponentially.
---
# 53. RETRY MULTIPLICATION
Calculate the real maximum execution attempts across all layers.
---
# 54. IDEMPOTENCY BEFORE RETRY
Before enabling automatic retries for mutations answer:
> Is the operation idempotent or deduplicated?
If not:
retrying is often far more dangerous than the initial failure.
---
# 55. SIDE EFFECT + ERROR
Scenario:
```text
side effect succeeds
↓
later local step fails
↓
whole operation reported failed
```
The caller may retry, executing duplicate external side effects.
---
# 56. PARTIAL FAILURE
Map all multi-step execution flows.
---
# 57. TRANSACTION ROLLBACK
Database transaction rollbacks cannot revert:
- dispatched emails
- completed HTTP calls
- captured payments
- uploaded files
---
# 58. ERROR AFTER COMMIT
Scenario:
```text
DB commit succeeds
↓
response serialization fails
↓
client sees 500
```
The client will retry an already committed mutation.
---
# 59. RESPONSE SERIALIZATION FAILURE
High-signal scenario demonstrating why idempotency is mandatory.
---
# 60. ERROR BEFORE COMMIT
External side effects may have already executed prior to the database failure.
---
# 61. COMPENSATION FAILURE
If an error handler attempts compensating transactions:
analyze what happens if the compensation itself fails.
---
# 62. ERROR HANDLER MUST NOT SPAWN GREATER ERROR
Example:
```text
catch error
↓
logger serializes circular object
↓
logging itself throws
```
The original error context becomes irrecoverably lost.
---
# 63. ERROR MIDDLEWARE
Audit the global exception handler.
Ask:
- what it intercepts
- what bypasses it
- sync vs async coverage
- framework-specific propagation semantics
---
# 64. ASYNC EXCEPTION
In certain runtimes unhandled async rejections bypass synchronous try/catch blocks.
Verify active runtime behavior.
---
# 65. UNHANDLED REJECTION
If the process can crash or merely log warnings:
verify production configuration.
---
# 66. UNCAUGHT EXCEPTION
Define process-level lifecycle policies.
Servers must not continue running with corrupted in-memory state merely to preserve superficial uptime.
---
# 67. PROCESS CRASH
Crashing is not always the worst outcome.
Process managers can restart cleanly.
However, critical operations must remain durable and retry-safe.
---
# 68. BACKGROUND JOB ERROR
Worker exceptions must properly control:
- retry scheduling
- failed state recording
- message acknowledgement
---
# 69. SWALLOWED JOB ERROR
Scenario:
```text
job fails
↓
catch + log
↓
worker returns success
↓
queue removes job
```
The background job is permanently lost.
---
# 70. THROW AFTER SIDE EFFECT
Conversely:
```text
job completes side effect
↓
non-critical logging fails
↓
worker throws
↓
queue retries
↓
side effect duplicates
```
---
# 71. ACK SEMANTICS
Map exactly when the message queue marks jobs as acknowledged.
---
# 72. DEAD LETTER
Permanent failures must transition to a terminal dead-letter queue.
---
# 73. POISON MESSAGE
A single poison pill message must not block queue processing indefinitely.
---
# 74. FAILURE METADATA
Failed jobs must preserve diagnostic context without needlessly logging sensitive payloads.
---
# 75. WEBHOOK ERROR
Incoming webhook error handling must consider provider retry schedules.
---
# 76. WEBHOOK 500
Providers will resend events upon 500 responses.
Event processing must be strictly idempotent.
---
# 77. WEBHOOK 200 BEFORE DURABILITY
Returning 200 before persisting events to durable storage means process crashes can result in lost events.
---
# 78. WEBHOOK 500 AFTER SIDE EFFECT
If side effects have already occurred, returning 500 causes providers to duplicate events.
---
# 79. WEBHOOK SIGNATURE ERROR
Invalid webhook signatures represent authorization rejections, not 500 internal server errors.
---
# 80. FILE ERRORS
Map:
- missing files
- permission denials
- disk full conditions
- partial writes
- storage service outages
---
# 81. DISK FULL
Never report success if metadata asserts file creation while disk write failed.
---
# 82. TEMP FILE CLEANUP
Error execution paths must clean up temporary files safely.
---
# 83. CLEANUP ERROR
Cleanup exceptions must not mask the original initiating failure.
---
# 84. OBJECT STORAGE FAILURE
Database records and object storage mutations can experience partial success.
---
# 85. CACHE ERROR
Ask:
> Should cache unavailability fail the business request?
If optional:
fallback gracefully to the database.
If cache acts as the authority, lock, or session store:
it is critical.
---
# 86. CACHE FAIL-OPEN
Presents severe correctness and security risks for:
- permission caches
- distributed locks
- rate limiters
---
# 87. CACHE FAIL-CLOSED
Can cause unnecessary outages if the cache exists solely for read performance acceleration.
---
# 88. AUTH ERROR HANDLING
Map:
- missing tokens
- malformed tokens
- expired tokens
- revoked credentials
- auth provider outages
---
# 89. AUTH PROVIDER DOWN
Never inform users that their:
```text
invalid password
```
was wrong when the authentication provider was simply unreachable.
---
# 90. AUTH ENUMERATION
Do not disclose excessive error details during login failures if the security model demands uniform error responses.
---
# 91. TOKEN REFRESH ERROR
Distinguish:
- refresh token expired
- refresh token revoked
- upstream auth network failure
---
# 92. AUTHORIZATION ERROR
Forbidden actions should yield 403, never 500.
---
# 93. RESOURCE HIDING
Returning 404 instead of 403 can be an intentional anti-enumeration strategy.
Do not alter without verifying security requirements.
---
# 94. VALIDATION ERROR FORMAT
Verify standardized structures for:
- field paths
- error codes
- messages
---
# 95. MULTIPLE VALIDATION ERRORS
Does the API:
- return all validation failures
- fail-fast on the first error
Both can be valid if consistently documented.
---
# 96. SANITIZATION ERROR
Malformed characters or encodings must not crash the error response serializer.
---
# 97. MALFORMED JSON
Must trigger a controlled 4xx error, not an unhandled parser stack trace.
---
# 98. OVERSIZED BODY
Payload size limit breaches must map cleanly to 413 or equivalent controlled errors.
---
# 99. MULTIPART ERROR
Malformed multipart requests must not leave orphan temporary files on disk.
---
# 100. RATE LIMIT ERROR
Verify:
- 429 status code
- headers
- machine-readable error payload
---
# 101. BUSINESS RULE ERROR
Examples:
```text
INSUFFICIENT_BALANCE
INVALID_TRANSITION
QUOTA_EXCEEDED
```
Must constitute deterministic client contracts.
---
# 102. BUSINESS ERROR LOG LEVEL
Expected client validation rejections should not be logged as ERROR.
Otherwise, operational monitoring fills with noise.
---
# 103. 4XX AS ERROR METRIC
Do not trigger pager alerts on every 404 or form validation error.
---
# 104. 5XX AS SIGNAL
Unexpected 5xx errors must remain clearly highlighted in monitoring.
---
# 105. LOG LEVEL TAXONOMY
Verify alignment of:
```text
DEBUG
INFO
WARN
ERROR
FATAL
```
against genuine operational impact.
---
# 106. DUPLICATE LOGGING
The same exception can be logged redundantly in:
- repository
- service
- controller
- global handler
generating 4 identical error events.
---
# 107. LOG ONCE WITH CONTEXT
Lower layers may log when adding context, but eliminate duplicate stack trace noise without value.
---
# 108. MISSING CONTEXT
Logging:
```text
Something went wrong
```
without:
- operation
- resource ID
- request ID
provides minimal troubleshooting value.
---
# 109. TOO MUCH CONTEXT
Never log:
- passwords
- tokens
- full credit card numbers
- sensitive document contents
---
# 110. STRUCTURED LOG
Where supported, prefer structured key-value attributes over string concatenation for searchable diagnostics.
P4 unless observability is genuinely degraded.
---
# 111. REQUEST ID
Errors must link directly to the incoming request trace.
---
# 112. USER ID IN LOG
Helpful for debugging, but audit privacy policies and cardinality limits.
---
# 113. TENANT ID
Essential for multi-tenant debugging under compliant privacy guidelines.
---
# 114. ERROR MONITORING
If APM tools (Sentry, Datadog) exist:
ensure expected errors do not create alert fatigue and unexpected errors are not suppressed.
---
# 115. `ignoreErrors`
Inspect broad ignore regexes that may hide real production crashes.
---
# 116. SAMPLING
Do not sample rare critical errors so aggressively that they disappear entirely.
---
# 117. FINGERPRINT
If custom grouping logic exists:
verify divergent root causes are not consolidated into a single misleading incident.
---
# 118. STACK TRACE
Internal monitoring must preserve stack traces.
Clients must never receive them.
---
# 119. SOURCE MAP / SYMBOL
Transpiled or obfuscated production stacks must be mapped back to source symbols.
---
# 120. TRACE
Distributed calls:
```text
API
↓
service A
↓
service B
↓
DB
```
must propagate error context across distributed traces.
---
# 121. TRACE ERROR STATUS
Verify that failing trace spans are flagged with error status.
---
# 122. METRICS
Key error metric dimensions:
- error rate
- category
- endpoint
- downstream dependency
Never use unbounded dynamic error messages as metric labels.
---
# 123. HIGH CARDINALITY
Never attach:
- stack traces
- request IDs
- user emails
as metric tag dimensions.
---
# 124. ALERTING
Alerts must target actionable symptoms rather than every single transient exception.
---
# 125. ERROR BUDGET / SLO
If the organization tracks SLOs:
verify error categorization accurately reflects availability calculations.
If SLOs are absent, do not mandate enterprise ceremony.
---
# 126. FALLBACK
For external dependencies fallback paths may exist.
Ask:
> Does the fallback return semantically valid data?
---
# 127. STALE FALLBACK
Serving stale cache data is acceptable for certain read-heavy views during outages.
Highly dangerous for:
- pricing
- permissions
- account balances
---
# 128. DEFAULT FALLBACK
Returning `false`, `0`, or `[]` is not a valid fallback if it corrupts business truth.
---
# 129. DEGRADED MODE
If an optional feature fails:
the backend may proceed without it.
---
# 130. PARTIAL RESPONSE
If an API emits partial data when an upstream fails:
the response contract must make the degradation explicit.
---
# 131. SILENT PARTIAL RESPONSE
Never return omitted fields pretending the response is complete when clients expect a full snapshot.
---
# 132. MULTI-UPSTREAM AGGREGATION
When aggregating sources A, B, and C:
define:
- fail-fast
- partial delivery
- fallback mechanisms
---
# 133. FAIL-FAST
Correct when every component is mandatory.
---
# 134. PARTIAL SUCCESS
Correct when features can operate with missing components.
The response must clearly flag missing data.
---
# 135. `Promise.all`
A single rejected promise aborts the entire aggregation.
Verify whether this matches domain intent.
---
# 136. `Promise.allSettled`
Allows partial aggregations, but callers must explicitly handle individual rejections.
---
# 137. CANCELLATION
If framework supports request cancellation:
differentiate client cancellation from server faults.
---
# 138. CLIENT DISCONNECT
Do not log routine client aborts as severe server errors.
---
# 139. CANCELLATION EXCEPTION
Never retry cancelled operations blindly.
---
# 140. SHUTDOWN ERROR
During graceful server shutdown in-flight requests and jobs may be aborted.
Verify classification and redelivery policies.
---
# 141. DEPLOYMENT TERMINATION
If SIGTERM interrupts a worker:
queues must redeliver uncompleted tasks.
---
# 142. STARTUP ERROR
Missing critical configuration must trigger fail-fast termination.
---
# 143. CONFIG PARSE ERROR
Never boot services with invalid default fallbacks if configuration is critical.
---
# 144. MIGRATION ERROR
If database migrations fail:
the application must not begin serving production traffic.
---
# 145. READY STATE
Readiness probes must reflect startup failures.
---
# 146. HEALTH ERROR
Health check endpoints must not crash if a single non-critical dependency is unreachable.
---
# 147. GRACEFUL DEGRADATION
If dependencies are optional:
health models should distinguish degraded states from dead states.
---
# 148. ERROR DURING ERROR RESPONSE
Serializers or templates may fail while constructing error payloads.
Provide a safe, minimal fallback response.
---
# 149. ERROR RECURSION
Global handlers must never re-throw identical exception types into infinite loops.
---
# 150. HEADERS ALREADY SENT
During streaming or chunked responses errors can occur after headers have already flushed.
Verify framework-specific recovery mechanisms.
---
# 151. STREAM ERROR
If a file download stream aborts midway:
the server cannot cleanly substitute an HTTP 500 JSON payload.
Requires client-side range or resume strategies.
---
# 152. SSE
If Server-Sent Events are used:
the error contract diverges from standard HTTP request-response cycles.
---
# 153. WEBSOCKET
Same for WebSockets.
If unused:
**NOT APPLICABLE**
---
# 154. WEBSOCKET ERROR
Distinguish:
- protocol violations
- authentication failures
- application-level message errors
- network disconnects
---
# 155. SSE ERROR EVENT
If the stream continues after individual business errors:
do not terminate the connection unnecessarily.
---
# 156. GRAPHQL
In GraphQL architectures:
HTTP 200 containing an `errors` array is an expected protocol pattern.
Do not impose REST assumptions blindly.
---
# 157. CLI / INTERNAL TOOL
Internal scripts and tools require stable error exit codes if automated systems depend on them.
---
# 158. BATCH ERROR
For batch operations specify:
- all-or-nothing
- partial acceptance
- per-item statuses
---
# 159. PER-ITEM ERROR
Must link directly back to the specific input record.
---
# 160. ERROR ORDER
Do not assume array index correlation if processing order is non-deterministic.
---
# 161. ASYNC JOB ERROR
Async job statuses must record:
- machine-readable error codes
- sanitized user-visible messages
- internal diagnostic references
---
# 162. RETRY COUNT
When jobs fail repeatedly:
ensure the final report preserves the original root cause rather than only the final symptom.
---
# 163. DEAD LETTER VISIBILITY
Failed tasks must not disappear without operational alerting and inspection tools.
---
# 164. USER-VISIBLE ASYNC FAILURE
When users trigger asynchronous tasks:
a clear mechanism must exist to inform them when tasks fail permanently.
---
# 165. EMAIL ERROR
If email delivery is non-critical:
queue retries in the background without failing the primary HTTP request.
---
# 166. EMAIL CRITICAL
If the email carries a mandatory one-time credential or action token:
the failure handling model must be strictly elevated.
---
# 167. NOTIFICATION ERROR
Push notification delivery issues rarely warrant rolling back database transactions.
Evaluate according to domain needs.
---
# 168. ANALYTICS ERROR
Never abort critical business flows due to analytics tracking errors.
---
# 169. OPTIONAL SIDE EFFECT
Classify side effects explicitly.
---
# 170. CRITICAL SIDE EFFECT
Never swallow critical payment or settlement errors.
---
# 171. COMPENSATION LOGGING
If compensating actions fail:
treat this as a high-severity operational incident.
---
# 172. UNKNOWN STATE
When the system cannot determine if an external operation succeeded:
do not report it as a simple FAILED.
Model explicitly as:
```text
UNKNOWN
RECONCILIATION_REQUIRED
```
---
# 173. RECONCILIATION
For unknown outcomes verify:
- status query polling
- idempotency key lookups
- scheduled reconciliation workers
---
# 174. PAYMENT UNKNOWN
Extremely sensitive.
Never retry charges blindly when the previous charge outcome remains unresolved.
---
# 175. FINALITY
Differentiate terminal rejections from transient failures across all error models.
---
# 176. RETRY BUDGET
Retries must not execute indefinitely without strict operational bounds.
---
# 177. OLD ERROR CODE
If clients depend on machine error codes:
renaming them constitutes a breaking contract change.
---
# 178. ERROR VERSIONING
Error response schemas form part of the public API contract.
---
# 179. CLIENT RETRY LOGIC
If client source code is available:
compare server error semantics against client retry policies.
---
# 180. CLIENT RETRIES WRONG ERRORS
Example:
```text
server 409 = business conflict
client retries 5x
```
amplifies traffic without resolving the conflict.
---
# 181. CLIENT DOES NOT RETRY TRANSIENT
Conversely:
network timeouts treated as fatal errors when operations are safe to retry.
---
# 182. USER MESSAGE
Internal error strings are not user-facing contracts.
Servers must emit stable machine codes; client UIs formulate localized messages.
---
# 183. LOCALIZATION
Never couple server control flow to localized text strings.
---
# 184. SUPPORT REFERENCE
Returning an opaque correlation ID for unexpected errors aids support workflows.
---
# 185. ERROR PRIVACY
Correlation IDs protect privacy far better than exposed stack traces.
---
# 186. SECURITY ERROR
Disclose only the minimum required information to callers during security rejections.
---
# 187. ACCOUNT ENUMERATION
Audit login and password reset error responses for identity enumeration leaks.
---
# 188. VALIDATION DETAILS
Detailed field-level validation errors are helpful for authenticated business forms.
Context determines appropriate detail exposure.
---
# 189. TIMING
Do not draw micro-timing conclusions without clear evidence.
Leave detailed crypto timing to specialized audits.
---
# 190. ERROR CACHE
Never allow CDNs or reverse proxies to cache transient 5xx responses inadvertently.
---
# 191. NEGATIVE CACHING
Caching 404s can be valid, but becomes dangerous during eventual consistency creation flows.
---
# 192. RETRY-AFTER
When the API knows when retries will succeed:
the `Retry-After` header provides strong value.
Do not mandate for every single error.
---
# 193. CIRCUIT BREAKER
If implemented:
verify how error thresholds trip the circuit.
---
# 194. CIRCUIT OPEN
Client behavior during open circuit states must be explicitly defined.
---
# 195. FALLBACK WHEN CIRCUIT OPEN
Verify semantic correctness of open-circuit fallbacks.
---
# 196. BULKHEAD
Downstream failures in one integration should not exhaust thread pools for unrelated endpoints.
Verify pool isolation where present.
---
# 197. ERROR STORM
Upstream dependency outages can trigger log flooding.
Evaluate log rate limiting where operational stability is at risk.
---
# 198. LOG LOSS
Excessively aggressive log rate limiting can erase the root cause incident.
---
# 199. ROOT CAUSE VS CASCADE
When a database drops, dozens of endpoints throw 500s simultaneously.
Monitoring must correlate symptoms back to the shared root cause.
---
# 200. FINDING FORMAT
Every serious finding must include:
```text
ID:
Severity:
Category:
Confidence:
Status:
Entry point:
Operation:
File/Class:
Function:
Error source:
Current error type:
Current client response:
Problem:
Evidence:
Failure Timeline:
T0:
T1:
T2:
T3:
Expected classification:
Actual classification:
Expected response/recovery:
Actual/Possible response/recovery:
Retryable:
YES / NO / CONDITIONAL / UNKNOWN
Side effect already possible:
YES / NO / UNKNOWN
Data impact:
User impact:
Operational impact:
Security/privacy impact:
Root cause:
Recommended remediation:
Regression/failure-injection test:
Production verification:
Complexity:
XS / S / M / L / XL
```
---
# 201. SEVERITY
Use:
## P0 - CRITICAL
- error handling causes duplicate irreversible financial transactions
- silent failures produce catastrophic data corruption
- error responses expose critical production secrets
- recovery paths trigger cross-user or cross-tenant data leaks
## P1 - HIGH
- false success results in permanent data loss
- retry mechanisms duplicate critical external side effects
- common failures result in permanently dropped jobs or events
- dependency outages cause uncontrolled cascading system failure
- production clients receive wrong semantics for core operations
## P2 - MEDIUM
- significant error classification or recovery flaw
- clients cannot determine correct recovery actions
- partial failure leaves inconsistent state without automated recovery
## P3 - LOW
- limited error handling edge case
- minor observability discrepancy
## P4 - IMPROVEMENT
- improved taxonomy, logging hygiene, or ergonomics without confirmed runtime bug
---
# 202. CONFIDENCE
Use:
```text
HIGH
MEDIUM
LOW
```
HIGH:
failure path is directly provable via code or test case.
MEDIUM:
strong code evidence, but runtime or downstream behavior not fully confirmed.
LOW:
depends on external provider or proxy semantics not accessible.
---
# 203. STATUS
Use:
```text
CONFIRMED
LIKELY
THEORETICAL
NOT VERIFIED
```
---
# 204. ERROR CLASS
Classify finding as:
```text
EXPECTED BUSINESS
EXPECTED CLIENT
TRANSIENT INFRASTRUCTURE
PERMANENT DEPENDENCY
UNEXPECTED INTERNAL
UNKNOWN OUTCOME
```
---
# 205. RETRY CLASS
Use:
```text
SAFE IMMEDIATE
SAFE WITH BACKOFF
SAFE ONLY WITH IDEMPOTENCY
REAUTH REQUIRED
USER ACTION REQUIRED
DO NOT RETRY
UNKNOWN
```
---
# 206. FALSE-POSITIVE PREVENTION
Before any P0/P1/P2 finding verify:
1. throw site
2. catch site
3. transaction boundaries and side effects
4. global handler interception
5. client response serialization
6. retry policies
7. queue and proxy behavior
8. log output
9. test suite coverage
10. external provider contracts
Do not flag an issue merely because a broad `catch` exists.
---
# 207. BROAD CATCH IS NOT AUTOMATICALLY A BUG
Broad catches are entirely valid at architectural boundaries.
What matters is how the error is handled.
---
# 208. `catch(Exception)` IS NOT AUTOMATICALLY A BUG
If it re-throws, maps, or preserves the causal chain, it can be completely correct.
---
# 209. CUSTOM EXCEPTION IS NOT AUTOMATICALLY BETTER
Never invent dozens of redundant exception classes without necessity.
---
# 210. DO NOT RETRY BLINDLY
Retries are business and reliability decisions, not default error handling patterns.
---
# 211. DO NOT RETURN EVERYTHING AS 200
Burying errors inside 200 OK payloads impairs client, proxy, and monitoring semantics.
GraphQL represents an exception where protocol rules differ.
---
# 212. DO NOT RETURN EVERYTHING AS 500
Expected input validation and business rejections are not server crashes.
---
# 213. DO NOT LOG EVERYTHING AS ERROR
Keep operational alarms actionable.
---
# 214. DO NOT SWALLOW JUST TO PASS TESTS
Silent failure is generally more hazardous than controlled failure.
---
# 215. DO NOT MODIFY CODE
During audit:
- do not change exception hierarchies
- do not add retries
- do not change status codes
- do not alter queue behavior
- do not reconfigure loggers
- do not insert circuit breakers
Complete the audit first.
---
# 216. OUTPUT - API_ERROR_HANDLING_AUDIT.md
Structure the final report:
## 1. Executive Summary
- error architecture
- taxonomy
- global handler
- retry model
- primary failure risks
- observability readiness
## 2. Error Flow Architecture
## 3. Error Taxonomy
## 4. Expected vs Unexpected Errors
## 5. Validation Error Audit
## 6. Business Error Audit
## 7. Authentication / Authorization Error Audit
## 8. Database Error Audit
## 9. External Dependency Error Audit
## 10. Timeout / Unknown Outcome Audit
## 11. Error Propagation / Wrapping Audit
## 12. False Success / Silent Failure Audit
## 13. Retry / Backoff Audit
## 14. Idempotency Interaction
## 15. Transaction / Partial Failure Audit
## 16. Job / Queue Error Audit
## 17. Webhook Error Audit
## 18. File / Storage Error Audit
## 19. Cache Error Audit
## 20. Fallback / Degraded Mode Audit
## 21. Logging Audit
## 22. Monitoring / Metrics / Tracing
## 23. Client Error Contract
## 24. Test Coverage
## 25. Findings Summary
| ID | Severity | Error class | Component | Problem | Retry class | Status |
|---|---|---|---|---|---|---|
## 26. P0 Findings
## 27. P1 Findings
## 28. P2 Findings
## 29. P3 Findings
## 30. P4 Improvements
## 31. Things Done Well
## 32. Unknown / Not Verified
## 33. Remediation Roadmap
---
# 217. ERROR MAPPING MATRIX
Construct:
| Source error | Internal class | HTTP/job result | Retry | Client code |
|---|---|---|---|---|
---
# 218. DATABASE ERROR MATRIX
| DB error | Current mapping | Expected semantics | Retryable | Risk |
|---|---|---|---|---|
---
# 219. DEPENDENCY FAILURE MATRIX
| Failure | Timeout | Retry | Fallback | Client result |
|---|---|---|---|---|
---
# 220. SIDE EFFECT FAILURE MATRIX
| Step | Side effect done | Error after | Duplicate on retry | Recovery |
|---|---|---|---|---|
---
# 221. JOB FAILURE MATRIX
| Job | Error | Retry count | Idempotent | Dead letter | Risk |
|---|---|---|---|---|---|
---
# 222. SECOND PASS - THROW SITE TRACE
Following initial audit, trace each P0/P1 candidate from throw location to final:
- response
- queue status
- log entry
- retry trigger
Do not skip intermediate layers.
---
# 223. SECOND PASS - SWALLOW ATTACK
Search repository-wide for catch blocks that:
```text
return null
return false
return []
return default
continue
```
Ask:
> Does the failure now appear as normal successful execution?
---
# 224. SECOND PASS - FALSE SUCCESS ATTACK
Inject failures into write pathways:
- database
- disk
- external provider
- event broker
Verify whether callers still receive success responses.
---
# 225. SECOND PASS - UNKNOWN OUTCOME
For external mutations:
```text
send
↓
provider processes
↓
response lost
```
Analyze how the error handler classifies the ambiguous state.
---
# 226. SECOND PASS - RETRY ATTACK
For each retry pathway assume the prior attempt successfully executed side effects.
Ask:
> What duplicates?
---
# 227. SECOND PASS - PROVIDER OUTAGE
Simulate:
```text
timeout
429
500
malformed 200
```
Verify application resilience.
---
# 228. SECOND PASS - DATABASE OUTAGE
Simulate:
- connection refused
- pool exhaustion
- query timeout
Examine response codes, log output, health probes, and retries.
---
# 229. SECOND PASS - QUEUE REDELIVERY
Worker executes side effects, then terminates before message acknowledgement.
Analyze redelivery consequences.
---
# 230. SECOND PASS - ERROR HANDLER FAILURE
Assume loggers, serializers, or telemetry fail inside the catch block itself.
Verify if a minimal safe fallback exists.
---
# 231. SECOND PASS - CASCADE FAILURE
A single dependency outage generates voluminous downstream errors.
Ask:
> Can monitoring correlate symptoms back to the primary root cause?
---
# 232. SECOND PASS - CLIENT BEHAVIOR
For each stable error code verify client handling:
- retries
- forced logout
- form error binding
- state conflict handling
- fatal crash screen
Identify discrepancies.
---
# 233. SECOND PASS - SECURITY LEAK
Inspect error payloads for:
- stack traces
- raw SQL queries
- internal hostnames
- file paths
- secrets
- provider payloads
---
# 234. SECOND PASS - EXPECTED ERROR NOISE
Trigger expected:
- validation errors
- 404 not found
- resource conflicts
Verify whether monitoring falsely registers incidents.
---
# 235. SECOND PASS - ASYNC FAILURE
For operations immediately acknowledging success:
inject permanent asynchronous failures downstream.
Verify how users are notified.
---
# 236. SECOND PASS - PARTIAL RESPONSE
If endpoints aggregate multiple data sources:
terminate one upstream service.
Verify whether the response clearly indicates partial degradation.
---
# 237. SECOND PASS - SHUTDOWN
Interrupt processes during:
- active HTTP requests
- background jobs
- webhook execution
Verify what gets retried and whether redelivery is safe.
---
# 238. FINAL QUALITY GATE
Before final response verify:
- expected and unexpected errors are clearly segregated
- domain rejections do not emit 500s
- internal bugs are not masked as validation errors
- critical catch blocks are traced to the caller
- false-success pathways are actively tested
- fallback values (`null`, `false`, `[]`) are not accepted blindly
- database errors map to specific constraint types
- provider 4xx errors are not blindly forwarded as our own 4xx
- timeout mutations include unknown-outcome analysis
- retries mandate idempotency protection
- nested retry multiplier effects are calculated
- transaction rollbacks are not assumed to revert external side effects
- worker errors do not accidentally acknowledge failing jobs
- duplicate webhook and job redeliveries are evaluated
- error handlers do not suppress original root causes
- stack traces and secrets are not leaked to clients
- expected 4xx errors do not flood ERROR logs
- client error handling aligns with server taxonomy
- permanent async failures provide recovery pathways
- P4 observability suggestions are separated from correctness bugs
---
# FINAL RULE
I do not want a report like:
> Add a global exception handler, log errors, and use retries.
That is not an error handling audit.
I am looking for problems like:
```text
database insert fails
↓
repository catches exception
↓
returns null
↓
service interprets null as "not found"
↓
controller returns 404
↓
real database outage appears to clients as missing resource
```
or:
```text
payment request reaches provider
↓
provider captures money
↓
HTTP response times out
↓
backend classifies timeout as FAILED
↓
generic retry runs
↓
second charge is attempted
```
or:
```text
worker sends email
↓
email succeeds
↓
analytics logging throws
↓
worker returns failure
↓
queue retries entire job
↓
same email is sent again
```
or:
```text
job DB write fails
↓
catch logs error
↓
worker returns success
↓
queue acknowledges job
↓
operation disappears permanently
```
or:
```text
third-party service returns 401
↓
backend passes through 401
↓
client assumes its own token expired
↓
user is logged out
↓
real issue was expired backend provider credential
```
or:
```text
database unavailable
↓
repository returns []
↓
API returns 200 []
↓
client displays "No records"
↓
operations team sees no obvious outage from API status codes
```
or:
```text
unexpected exception
↓
global handler returns full stack trace
↓
response contains internal paths, SQL details and infrastructure names
```
These are the error handling problems you need to find.
Think through:
- failure source
- propagation
- classification
- partial side effects
- unknown outcomes
- retryability
- client semantics
- operational visibility
- recovery
For each serious finding you must be able to answer:
> Exactly where does the error originate?
> Where is it first caught?
> Could side effects have already occurred?
> What does the caller believe happened?
> What response or job status is produced?
> Will anything trigger a retry?
> If retried, is it safe?
> How will the operations team detect the failure?
If not provable:
**NOT VERIFIED.**
If external mutation outcome is unresolved:
**UNKNOWN OUTCOME.**
If it is merely better exception taxonomy organization:
**P4 - IMPROVEMENT.**
It is better to find 6 genuine false-success, retry, or recovery flaws than to write 100 generic `try/catch` recommendations.
The goal is to produce a forensically precise error handling audit that can be directly converted into:
- failure-injection tests
- error mapping corrections
- retry policy adjustments
- idempotency safeguards
- queue recovery mechanisms
- client contract fixes
- operational observability alerts
- production-safe failure models分类与标签
编程开发、接口错误处理、重试安全、幂等性、故障注入测试、后台任务恢复