Why HTTP Status Codes Are Not Enough for Microservice Errors

HTTP status codes are one of the foundations of REST API design. They provide a standardized way to communicate whether a request succeeded, failed because of a client problem, or encountered a server-side error.

For simple applications, this can appear sufficient.

A 404 Not Found tells us a resource does not exist. A 400 Bad Request indicates a problem with the request. A 500 Internal Server Error tells us something went wrong on the server.

But once an application becomes part of a distributed system, these classifications leave important questions unanswered.

What exactly failed? Which service owns the failure? Can the operation be retried? Is the error permanent? What should the caller do next?

These questions became particularly important while designing NERV Exception, a reusable Java and Spring Boot exception-handling library.

The central lesson is that HTTP status codes describe the outcome of an HTTP interaction, but they do not fully describe the meaning of an application failure.

1. One HTTP Status Can Represent Multiple Failures

Consider an order-processing application.

The following operations might all return 409 Conflict:

  • An order has already been processed.
  • A payment has already been captured.
  • Inventory is reserved by another transaction.
  • An optimistic locking conflict prevents an update.

These failures share an HTTP classification, but their business meanings are different.

HTTP/1.1 409 Conflict

{
  "status": 409,
  "message": "Conflict"
}

From the consumer's perspective, this response is ambiguous.

Should the user refresh the page? Should the application stop processing? Should it reload the resource and retry? Should it initiate reconciliation?

The HTTP status alone cannot answer these questions.

Introduce application-specific error codes

A more expressive response adds a stable application error code.

{
  "code": "ORDER_ALREADY_PROCESSED",
  "message": "The order has already been processed",
  "status": 409
}

Another conflict can use the same HTTP status but a different code:

{
  "code": "INVENTORY_RESERVATION_CONFLICT",
  "message": "Inventory is reserved by another transaction",
  "status": 409
}

Now the consumer can distinguish between two failures without interpreting message text.

This is the first important distinction: HTTP status codes classify failures; application error codes identify them.

2. Human-Readable Messages Are Not Stable Contracts

Another common approach is to rely on exception messages.

For example:

{
  "status": 409,
  "message": "Order has already been processed"
}

A frontend might compare the message to determine which notification to display.

This works until someone changes the wording.

Old:
"Order has already been processed"

New:
"This order has already been completed"

The business condition has not changed, but a consumer depending on the original message may break.

Messages can change because of localization, improved wording, security requirements, or routine refactoring.

Stable error codes provide a more reliable integration contract.

{
  "code": "ORDER_ALREADY_PROCESSED",
  "message": "This order has already been completed",
  "status": 409
}

The message remains useful for people, while the code remains stable for software.

An important consequence follows: changing a published error code can be a breaking API change, even when the HTTP status and response schema remain unchanged.

3. Microservice Boundaries Introduce Another Layer of Meaning

Consider a distributed application with three services.

API Gateway
     |
     v
Order Service
     |
     v
Payment Service

A client sends a request to Order Service.

Order Service calls Payment Service, which rejects the operation because the payment was already processed.

HTTP/1.1 409 Conflict

{
  "code": "PAYMENT_ALREADY_PROCESSED",
  "message": "Payment has already been processed",
  "status": 409
}

Order Service must now decide how to represent the downstream failure to its own caller.

One possibility is to replace it with a generic error.

{
  "code": "DOWNSTREAM_SERVICE_ERROR",
  "message": "Unable to process order",
  "status": 500
}

This can be appropriate when the downstream failure should be abstracted from the public API.

But it can also discard useful information.

Another possibility is to preserve the downstream application error code.

{
  "code": "PAYMENT_ALREADY_PROCESSED",
  "message": "Payment has already been processed",
  "status": 409
}

This gives the caller more information, but it raises questions about ownership and compatibility.

Does Order Service need to recognize every Payment Service error code? Should it trust the downstream classification? What happens when Payment Service introduces a new error?

HTTP status codes do not resolve these architectural decisions.

They require a defined error contract and an explicit propagation policy.

4. A Shared Contract Does Not Require a Shared Business Catalog

One possible solution is to define all application error codes in a shared Java library.

public enum ApplicationErrorCode {

    ORDER_ALREADY_PROCESSED,
    PAYMENT_ALREADY_PROCESSED,
    CUSTOMER_DISABLED,
    INVENTORY_RESERVATION_CONFLICT

}

This example is illustrative rather than an API from NERV Exception.

A centralized catalog initially seems convenient.

Every service knows the same codes, and every error has a common definition.

But as services evolve independently, the shared catalog can become a source of coupling.

A new payment-specific error may require updating a library used by Order Service, Customer Service, and Inventory Service.

These services may have different release schedules and no reason to understand one another's business failures.

A more flexible approach separates the shared response contract from application-owned error definitions.

Shared Error Contract
    |
    +-- code
    +-- message
    +-- status
    +-- category
    +-- retryable
    +-- origin
    +-- details

Payment Service
    |
    +-- PAYMENT_ALREADY_PROCESSED
    +-- PAYMENT_DECLINED

Order Service
    |
    +-- ORDER_ALREADY_PROCESSED
    +-- ORDER_NOT_FOUND

The services agree on how errors are communicated without requiring every service to own the same error catalog.

This principle influenced the design of NERV Exception.

Its Feign integration can represent unknown downstream codes through RemoteNervErrorCode, allowing applications to retain useful error information without registering every remote business definition locally.

However, when a downstream code is registered locally, the local definition determines the resolved status, category, and retryability.

This is an intentional distinction between unknown remote definitions and locally recognized codes.

It also demonstrates why error-code ownership and local registration should be treated as architectural decisions.

5. HTTP Status Does Not Tell You Whether Retrying Is Safe

A particularly dangerous assumption is that server-side errors should automatically be retried.

Consider:

HTTP/1.1 503 Service Unavailable

A consumer may interpret this as a temporary failure and retry the operation.

But the HTTP status alone does not establish whether the operation is safe to repeat.

The lost-response problem

Imagine the following payment workflow:

Order Service
     |
     | Submit payment
     v
Payment Service
     |
     | Payment succeeds
     v
Payment Provider
     |
     X Response lost

Order Service experiences a timeout.

The payment may have succeeded, but the caller cannot determine the outcome from the transport failure alone.

Retrying without idempotency protection could cause duplicate processing.

This is why retryability should be represented explicitly but interpreted carefully.

{
  "code": "PAYMENT_PROVIDER_UNAVAILABLE",
  "message": "Payment provider is temporarily unavailable",
  "status": 503,
  "category": "DEPENDENCY",
  "retryable": true
}

The response provides recovery guidance, but it does not guarantee that retrying the business operation is safe.

Applications must still consider idempotency, retry limits, backoff, timeouts, and unknown outcomes.

NERV Exception's Feign integration can classify retryable downstream failures using Feign's RetryableException.

It does not automatically install a retry policy or guarantee retry execution.

Retry classification, retry execution, and business recovery are separate responsibilities.

6. Error Categories Provide Additional Context

HTTP status codes describe the result of an HTTP interaction. Application error categories can describe the nature of the underlying failure.

Consider these illustrative classifications:

Error HTTP Status Category Retryable
Invalid request 400 CLIENT No
Order already processed 409 BUSINESS No
Dependency unavailable 503 DEPENDENCY Potentially
Unexpected internal failure 500 SYSTEM Policy-dependent

These are example application classifications, not a universal mapping required by NERV Exception.

NERV Exception represents categories as strings, allowing applications to define domain-appropriate categories.

This flexibility is useful, but teams should establish consistent naming conventions.

An important design principle is to keep HTTP status, category, and retryability independent.

Deriving one mechanically from another can produce incorrect recovery behavior.

7. A More Complete Error Contract

Once we recognize the limitations of HTTP status codes, the natural next step is to define a richer response contract.

NERV Exception provides a response model called NervErrorResponse.

An illustrative response using its supported fields looks like this:

{
  "code": "ORDER_ALREADY_PROCESSED",
  "message": "The order has already been processed",
  "status": 409,
  "retryable": false,
  "category": "BUSINESS",
  "traceId": "abc123",
  "spanId": "def456",
  "path": "/api/orders/123/process",
  "timestamp": "2026-11-20T08:30:00Z",
  "origin": {
    "service": "order-service",
    "instance": "order-service-1",
    "version": "1.0.0",
    "environment": "production"
  },
  "details": {}
}

The business error code, category, and example values above are illustrative. Diagnostic fields depend on the application's configuration and available context.

Each field has a distinct responsibility:

  • code: A stable application error identifier.
  • message: A readable explanation suitable for the intended consumer.
  • status: The HTTP status associated with the response.
  • retryable: Guidance about potential recovery.
  • category: A broader classification of the failure.
  • traceId and spanId: Correlation information when tracing context is available.
  • path: The request path associated with the generated response.
  • timestamp: When the response was generated.
  • origin: Information about the service associated with the error.
  • details: Structured, error-specific information when appropriate.

A consistent response structure allows consumers to implement predictable error-handling behavior.

But consistency should not be confused with exposing every internal detail.

Public APIs should return safe messages and avoid leaking stack traces, database details, credentials, or internal infrastructure information.

Internal logs and tracing systems can retain deeper diagnostic information under appropriate access controls.

8. Error Propagation Is Not Always Lossless

There is another subtlety in distributed systems.

Even if two services use the same error response contract, propagating an error does not necessarily preserve every field unchanged.

For example, Payment Service might generate an error while processing:

POST /payments

Order Service receives the error while processing:

POST /orders

Which path should appear in the final response?

The downstream path identifies where the original error occurred. The current path identifies the request being handled by Order Service.

These represent different contexts.

In the reviewed NERV Exception implementation, the downstream exception preserves supported remote information such as the message, origin, and details.

It does not retain the original downstream trace identifier, span identifier, path, or timestamp for direct reuse.

A regenerated HTTP response uses the receiving application's current context for those fields.

This illustrates why an error contract and a distributed tracing system serve different purposes.

Error codes help identify failures. Distributed tracing helps reconstruct how those failures moved through the system.

Neither completely replaces the other.

9. Consumers Must Be Prepared for Unknown Errors

In an independently deployed microservice architecture, services evolve at different speeds.

Payment Service might introduce:

PAYMENT_REQUIRES_ADDITIONAL_VERIFICATION

Order Service may not recognize the new code immediately.

This should not automatically break error handling.

A robust consumer should be able to:

  • Preserve the unknown error identifier when appropriate.
  • Apply safe fallback behavior.
  • Use status and other contract fields as additional context.
  • Record sufficient diagnostic information.
  • Avoid assuming every possible error code is known in advance.

This is particularly important when services do not share release schedules.

Error-code compatibility should be considered part of API evolution, not merely an exception-handling implementation detail.

10. What Should Clients Actually Depend On?

A well-designed API error contract provides multiple levels of information.

Consumers should use the appropriate level for the decision they need to make.

Consumer Need Relevant Information
Determine HTTP outcome HTTP status
Identify a business failure Application error code
Display a readable explanation Safe message
Classify the failure Category
Evaluate potential recovery Retryability and operation semantics
Investigate an incident Tracing and origin information
Handle field validation Structured details

No single field should be expected to answer every question.

The goal is to make the response expressive enough that consumers can act without guessing.

11. Design Principles for Production Microservices

Based on these considerations, I recommend several principles when designing error contracts for distributed systems.

Keep HTTP status codes meaningful

Don't replace HTTP semantics with application codes. Use appropriate status codes and supplement them with more precise information.

Make application error codes stable

Treat published error codes as API contracts. Avoid changing their identifiers or meanings casually.

Separate error classification from recovery

Status, category, and retryability should express distinct concerns. A retryable classification does not guarantee safe retry execution.

Preserve service autonomy

Share the error response structure without forcing every service to import every other service's business catalog.

Support unknown downstream codes

Independently deployed services must tolerate new errors introduced by their dependencies.

Protect diagnostic information

Expose information useful to consumers, but keep sensitive internal details in appropriately secured logs and tracing systems.

Review error compatibility

Changes to codes, categories, status mappings, or retryability can affect consumers even when the JSON schema remains unchanged.

Final Thoughts

HTTP status codes are essential to REST API design.

They provide a standardized foundation for communicating request outcomes.

But in microservice architectures, that foundation is not enough on its own.

Consumers need to distinguish business failures from infrastructure problems, understand whether recovery might be appropriate, and correlate errors across service boundaries.

Stable application error codes, meaningful classifications, structured details, and tracing information help address those requirements.

These principles influenced the design of NERV Exception, but they apply equally to teams building their own exception-handling infrastructure.

The objective isn't to replace HTTP status codes.

It's to recognize their limitations and build a more expressive contract around them.

HTTP status codes tell consumers what happened at the protocol level. A well-designed error contract helps them understand what the failure means.


About NERV Exception

NERV Exception is an open-source Java and Spring Boot library focused on consistent error contracts, exception handling, error code resolution, and integration with frameworks such as Spring Web and OpenFeign.

It is part of the broader NERV ecosystem of reusable Java libraries.

Explore the projects on GitHub.

For more articles on Java, Spring Boot, and production-oriented software architecture, visit CzetsuyaTech.

0 Comments

Post a Comment

Post a Comment (0)

Previous Post Next Post
NERV Open Source
Building production Spring Boot systems?

Explore NERV — open-source Java libraries for audit trails, persistence, exception handling, and reliable event-driven architecture.