Error Handling Best Practices for Production Applications


Every production application will encounter failures. A database connection can drop, a third-party API can time out, a user can submit invalid data, a deployment can introduce a defect, or a message can be processed twice. Reliable software is not software that never fails. It is software that detects failures, limits their impact, communicates clearly, preserves data integrity, and gives engineers enough information to recover.
Error handling is therefore much more than adding try/catch blocks. It is a design discipline connecting application architecture, API contracts, security, observability, testing, and operations. A poorly designed handler can hide a defect, leak sensitive information, or make an incident harder to investigate. A deliberate strategy makes failures predictable and manageable.
This guide covers practical error-handling techniques for backend services, APIs, and frontend applications. Examples use Python, JavaScript, and HTTP, but the principles apply across most technology stacks.
Table of Contents
Before deciding how to handle a failure, determine what kind of problem occurred and whether the caller or system can do anything about it. Treating every problem as an internal server error creates confusing APIs. Treating every exception as recoverable can conceal serious defects.
Expected errors are part of normal application behavior: invalid form data, incorrect login credentials, a missing record, insufficient permissions, a duplicate booking, or a rate limit. These conditions should usually be represented explicitly in business logic. They are not necessarily defects and should produce an appropriate response or recovery path.
Unexpected failures include programming bugs, broken assumptions, unavailable infrastructure, malformed dependency responses, and conditions the application cannot safely resolve. Examples include an unhandled null value, a database outage, a corrupted file, or an unexpected exception from an external SDK. These failures need diagnostic information and may need to trigger alerts.
A useful classification asks three questions: Can the caller correct the request? Can the system retry safely? Does an engineer need to investigate? The answers influence the response code, log severity, and recovery behavior.
An error is any condition that prevents an operation from completing as intended. An exception is a language-level mechanism for signaling a problem and changing normal control flow. A process failure is broader: the application may crash, run out of memory, lose its host, or be terminated before application-level handlers can run. Exception handling cannot replace infrastructure resilience; production systems also need health checks, process supervision, restart policies, backups, and reliable deployments.
Define how important operations should behave when they fail before implementing individual handlers. A practical strategy answers five questions:
Consider a payment operation. Invalid payment details, a declined payment, a duplicate submission, a payment-provider outage, and an unexpected application defect are different situations. They require different responses and operational treatment. A generic message such as “Payment failed” is not a complete strategy.
Define which outcomes are normal business behavior. A search returning no results is usually an empty result, not an exception. An incorrect password is an expected authentication outcome. A database connection dropping during a write is an operational failure. Modeling these distinctions keeps application code and monitoring meaningful.
Catch an exception where the application can make a useful decision. Catching too early may hide the original problem; catching too late may expose implementation details or leave the caller without a controlled response.
Prefer specific exception types instead of broad catch-all handlers throughout the application:
try:
customer = customer_repository.get(customer_id)
except CustomerNotFoundError:
return {"error": "Customer not found"}, 404
except DatabaseUnavailableError:
logger.exception("Database unavailable while loading customer")
return {"error": "Service temporarily unavailable"}, 503
Avoid catching BaseException in ordinary Python application code because it includes process-control exceptions such as KeyboardInterrupt and SystemExit. In JavaScript, remember that code can throw values that are not instances of Error; normalize unknown values at a system boundary before relying on properties such as message.
A broad exception handler is appropriate at a deliberate boundary, such as a web request handler or worker entry point, where its purpose is to prevent an unhandled application exception from escaping. It should record the failure and return or publish a safe failure outcome. It must never silently report success.
Keep try blocks focused. Wrap only the operation expected to fail. Large blocks make it difficult to identify the failing statement and can accidentally catch exceptions from unrelated code. Also preserve the original cause when translating low-level errors into domain errors. Python supports exception chaining with raise ... from exc; JavaScript supports an error cause property. Public responses should not expose internal stack traces, but protected diagnostics should retain the underlying failure.
Custom exceptions give an application a vocabulary for its own domain. They help distinguish a missing customer, a duplicate order, a rejected business rule, or an unavailable dependency.
class AppError(Exception):
"""Base class for application-level errors."""
class NotFoundError(AppError):
pass
class ConflictError(AppError):
pass
class ValidationError(AppError):
pass
class DependencyUnavailableError(AppError):
pass
Add structured attributes when other parts of the application need reliable data. A validation exception might include a field name and machine-readable code. Avoid making callers parse human-readable exception messages because messages can change or be translated. Keep the hierarchy small and aligned with the business domain; a class for every minor variation creates needless complexity.
An API is a contract between a service and its consumers. That contract includes failure behavior as well as successful responses. Clients need predictable status codes and response structures so they can display useful feedback and decide whether to retry.
Use HTTP status codes according to the meaning of the failure:
| Status | Meaning | Typical example |
|---|---|---|
| 400 Bad Request | Request is malformed | Invalid JSON syntax |
| 401 Unauthorized | Authentication is missing or invalid | Expired access token |
| 403 Forbidden | Caller lacks permission | Access to another tenant's record |
| 404 Not Found | Resource does not exist or is intentionally undisclosed | Unknown order ID |
| 409 Conflict | Request conflicts with current state | Duplicate booking |
| 422 Unprocessable Content | Request is syntactically valid but semantically invalid | Invalid field combination |
| 429 Too Many Requests | Rate limit exceeded | Too many login attempts |
| 500 Internal Server Error | Unexpected application failure | Unhandled defect |
| 502 Bad Gateway | Invalid upstream response | Broken provider response |
| 503 Service Unavailable | Service temporarily unavailable | Maintenance or dependency outage |
| 504 Gateway Timeout | Upstream response timed out | Slow dependency |
The distinction between 401 and 403 matters: 401 concerns authentication, while 403 concerns authorization. A service may intentionally return 404 instead of 403 when revealing that a protected resource exists would disclose sensitive information.
Use a stable response schema. For example:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request contains invalid fields.",
"details": [
{
"field": "email",
"code": "INVALID_FORMAT",
"message": "Enter a valid email address."
}
],
"request_id": "req_8f3a2c"
}
}
The exact schema is a design choice. Important properties are stable machine-readable codes, safe human-readable messages, optional field-level details, and a request identifier support teams can use to locate the corresponding log or trace. Do not make clients parse message text, and never return stack traces, SQL statements, credentials, or raw internal exception messages. For a standard format, consider Problem Details for HTTP APIs (RFC 9457).
Validate untrusted input at the boundary: request bodies, query and path parameters, uploaded files, and webhook payloads. Check types, required fields, ranges, formats, size limits, and allowed values. Boundary validation improves feedback, but does not replace database constraints or domain rules. Storage constraints remain essential for invariants such as uniqueness and referential integrity, especially when concurrent requests can race.
A layered application should assign clear responsibilities:
A repository can raise CustomerNotFoundError; a service can decide whether that is a valid business outcome; and the HTTP layer can map it to a 404 response. The service remains reusable from an API, scheduled job, or command-line tool. Avoid returning HTTP status codes from deep inside business logic because this couples domain behavior to one transport protocol.
Some failures are temporary. Retrying can improve reliability, but indiscriminate retries can amplify an outage or duplicate an operation.
Every network call to a database, HTTP service, queue, or other dependency should have an intentional timeout. Retry only failures that are plausibly temporary, such as selected connection errors, rate limits, or transient server errors. Use a bounded number of attempts and exponential backoff, often with jitter:
import random
def retry_delay(attempt: int) -> float:
base = min(0.5 * (2 ** attempt), 8.0)
return base + random.uniform(0, 0.25)
A production retry policy must also enforce a total deadline, classify retryable errors, and stop when the operation is no longer useful. Respect a provider's Retry-After guidance where applicable. Do not retry every 4xx response, and avoid stacking retry policies across layers.
A retry is safe only when repeating the operation will not create an unintended additional effect. Reads are generally safe to retry; creating a payment, placing an order, or sending a message may not be. Use idempotency keys or deduplication for important writes. The client supplies a unique key for one logical operation; the server stores the key and result so a repeated request returns the original outcome instead of performing the action again. A timeout does not prove that a remote write failed: the remote system may have completed it while its response was lost.
A circuit breaker temporarily stops calls to a dependency that is repeatedly failing. Its common states are closed (calls flow normally), open (calls fail quickly), and half-open (limited test calls check recovery). Circuit breakers work best with timeouts, metrics, and a defined recovery policy.
Graceful degradation preserves essential functionality when a non-critical component is unavailable. A product page might load while recommendations are omitted; a dashboard might show cached data with a timestamp; a notification service might queue messages. Do not silently degrade critical operations such as payments, permission checks, or inventory updates. A fallback must preserve correctness and security.
A workflow may update a database, call an external service, and publish a message. If a later step fails, earlier side effects may already have happened. Use database transactions for changes that must succeed or fail together. Keep transactions short and avoid holding locks while waiting on slow network calls. For workflows spanning independent services, consider a saga or compensating action rather than assuming one transaction can roll back every external effect.
Release resources reliably. Python context managers and equivalent constructs in other languages close files, connections, and locks even when an exception occurs:
with open("report.txt", encoding="utf-8") as report:
contents = report.read()
For background jobs, make task state explicit: pending, running, succeeded, failed, or retrying. Store enough information to diagnose failures, avoid processing the same message twice, and route repeatedly failing messages to a dead-letter queue. A job should not be marked successful until its required effects have completed.
Logs should help engineers determine what happened, where it happened, how often it is happening, and which operation or dependency was involved. A message such as Something went wrong is rarely enough.
Prefer structured logs with timestamp, severity, service name, environment, deployed version, request or trace identifier, operation name, exception type, and relevant dependency details. In Python, logger.exception() records the current exception and traceback inside an exception handler:
try:
order = order_repository.create(payload)
except DatabaseError:
logger.exception(
"Order persistence failed",
extra={"request_id": request_id, "operation": "create_order"},
)
raise
Log at the level that reflects the event. Expected validation failures may not need error-level logs. Unexpected failures generally warrant error-level records. Avoid logging the same exception at every layer; record it where it is handled or where the most useful context is available.
Never log passwords, access tokens, private keys, full payment details, or unnecessary personal data. Redact sensitive fields before data reaches the logging pipeline, and apply appropriate access controls and retention policies. For a deeper look, see the application logging guide.
Logs are useful for individual investigations, but production reliability also requires aggregate signals. Track request rate, error rate, latency percentiles, error counts by route and status, dependency timeouts, retry volume, queue depth, failed jobs, database connection pool saturation, and process restarts.
Track expected client errors separately from unexpected server failures. A sudden increase in validation errors can still reveal a broken frontend release or incompatible API change. Distributed tracing connects work across services: propagate trace context through HTTP calls and message queues so engineers can follow one request from browser to API, database, and downstream provider.
Alerts should be actionable and tied to user impact. Alert on sustained error-rate increases, latency breaches, unavailable critical dependencies, or failed background workflows rather than every isolated exception. Define service-level indicators (SLIs), service-level objectives (SLOs), and error budgets where appropriate. When reliability falls below its objective, teams can prioritize restoring service and reducing risk.
The frontend must distinguish between a failed request, invalid form input, an expired session, an unavailable service, and an unexpected client-side defect.
In JavaScript, fetch() rejects for certain network failures, but an HTTP 404 or 500 still resolves to a Response object. Check response.ok explicitly:
async function loadProfile() {
const response = await fetch("/api/profile");
if (!response.ok) {
throw new Error(`Profile request failed: ${response.status}`);
}
return response.json();
}
Translate known API error codes into useful interface states. Show validation messages beside relevant fields, offer a retry action for temporary failures, and provide a sign-in path when authentication expires. Do not show raw stack traces or internal server messages.
Design loading, success, empty, and error states deliberately. A search with no results is usually an empty state, not an error. A failed save should make it clear that the change was not confirmed. If a form submission times out and the operation might have succeeded, do not encourage repeated submissions unless the operation is protected against duplicates.
Framework error boundaries can isolate rendering failures, but they do not replace handling rejected promises, failed network requests, or event-handler errors. Log client-side exceptions with release and route context while filtering personal information.
Error messages are an information boundary. Detailed diagnostics belong in protected logs; public responses should disclose only what the caller needs to take the next appropriate action.
Avoid exposing stack traces, source-code paths, SQL queries, database schema details, secret values, access tokens, cookies, authorization headers, internal hostnames, private IP addresses, or unnecessary personal information. Use generic authentication responses where appropriate to reduce account enumeration. Apply authorization checks to every protected operation; hiding an error message is never a substitute for access control.
Treat error details received from third-party services as untrusted input. Sanitize them before logging or rendering, and avoid reflecting arbitrary provider responses to clients. Ensure log platforms, monitoring dashboards, and support tools have appropriate access controls and retention settings. For related security practices, see the API vulnerability guide.
A happy-path test proves that an operation can succeed under expected conditions. It does not prove safe behavior when something goes wrong. Include failure scenarios in unit, integration, and end-to-end tests.
Test missing and malformed input, unauthenticated and unauthorized requests, missing records, conflicting state transitions, database connection loss, constraint violations, transaction rollback, dependency timeouts, rate limits, malformed responses, duplicate submissions, file permission errors, queue failures, unexpected request-boundary exceptions, frontend offline states, expired sessions, and failed submissions.
Mock dependencies for focused unit tests, but also run integration tests against real test infrastructure where practical. Mocks can verify that a timeout is handled; they cannot fully reproduce connection pool exhaustion, transaction behavior, or network timing.
Verify both the response and the side effects. A failed payment test should check that no duplicate charge or inconsistent order state was created. A database error test should check that the transaction rolled back. An unexpected-exception test should verify that the client receives a safe response and that diagnostic records include a request identifier without leaking secrets.
Use controlled dependency failures in staging to test recovery. Keep experiments scoped and reversible; do not introduce deliberate failures into production without an approved resilience-testing plan. For broader techniques, see the Python testing guide.
Catching and ignoring exceptions. Empty handlers hide failures and create false success. Handle the condition, log it where appropriate, or propagate it.
Catching every exception everywhere. Broad handlers can turn programming defects into misleading business responses. Catch broadly only at a deliberate boundary.
Returning success after a failed operation. A fallback must be explicit and must not claim that an important action completed when it did not.
Exposing internal exception messages. Raw messages may reveal secrets or implementation details. Return safe public messages and keep diagnostics private.
Retrying without limits. Unbounded retries can amplify outages and exhaust resources. Use deadlines, backoff, jitter, and retry classification.
Retrying non-idempotent actions blindly. A timeout does not prove that a remote write failed. Use idempotency keys and deduplication.
Logging without context—or logging too much. Logs need correlation and operation details, but must not contain credentials or unnecessary personal information.
Using exceptions for normal control flow. Expected outcomes such as an empty search result should usually be represented directly.
Handling errors inconsistently across endpoints. Different response shapes force every client to implement special cases. Centralize response mapping and document the contract.
Testing only successful requests. Failure behavior is part of the feature and deserves explicit tests.
Before releasing a service, review the following:
Reliable error handling is not about preventing every failure or surrounding every function with a handler. It is about designing predictable behavior when assumptions break. Classify failures accurately, handle them at the right layer, communicate through stable contracts, preserve diagnostic context, and recover only when doing so is safe.
Start with the operations that matter most: authentication, payments, data writes, integrations, and background jobs. Define their failure modes, test those paths, and make sure production monitoring can reveal when behavior changes. The result is software that is easier to debug, safer to operate, and more trustworthy—not because it never fails, but because failures are contained, understood, and handled deliberately.

Learn how to design structured application logs, choose severity levels, correlate requests, protect sensitive data, and build reliable observability for production systems.
Read
Learn how to design robust APIs with clear resource models, HTTP semantics, secure authentication, reliable errors, versioning, documentation and scalability.
Read
Mastering SQL is the cornerstone of backend development excellence, empowering developers to build scalable, efficient, and data-driven applications that drive business success.
Read