- semua error menjadi 500
- semua error menjadi 400
- stacktrace bocor ke response
- error code tidak stabil
- consumer tidak tahu boleh retry atau tidak
- operator tidak bisa membedakan bug, bad request, dependency outage, dan authorization failure
- alert terlalu noisy karena domain error dianggap incident
- incident sulit dianalisis karena correlation ID tidak ada

An error response should tell the client what happened at the contract boundary,
while logs and telemetry tell operators what happened inside the system.

- path not found
- method not allowed
- unsupported media type
- unacceptable response media type

- query param expected int but got string
- invalid enum value
- malformed JSON
- invalid date format
- body cannot be deserialized

400 Bad Request

- required field missing
- field too long
- invalid currency code
- start date after end date
- quantity below minimum

400 Bad Request

- missing token
- expired token
- invalid signature
- invalid issuer
- invalid audience

401 Unauthorized

- authenticated user lacks permission
- service identity not allowed
- tenant boundary violation
- object-level access denied

403 Forbidden

- quote cannot be submitted from current state
- catalog version is not active
- pricing rule is not applicable
- order cannot be cancelled after fulfillment starts
- duplicate quote reference exists

- database unavailable
- connection pool exhausted
- Kafka broker unavailable
- downstream timeout
- serialization bug
- unexpected null pointer

500 Internal Server Error
503 Service Unavailable
504 Gateway Timeout

- tenant request quota exceeded
- gateway limit exceeded
- service overloaded
- bulkhead full
- load shedding triggered

429 Too Many Requests
503 Service Unavailable

{
  "errorCode": "QUOTE_INVALID_STATE",
  "message": "Quote cannot be submitted from its current state.",
  "details": [
    {
      "field": "status",
      "reason": "Expected DRAFT or READY_FOR_SUBMISSION."
    }
  ],
  "correlationId": "c-123"
}

- stacktrace
- SQL query
- table/column names unless intentionally public
- internal hostnames
- token contents
- secret names/values
- customer data unrelated to caller
- internal class names as primary error contract

{
  "error": "java.lang.NullPointerException at com.company.quote.PricingService line 183"
}

{
  "errorCode": "INTERNAL_ERROR",
  "message": "The request could not be processed.",
  "correlationId": "c-123"
}

QUOTE_NOT_FOUND
QUOTE_INVALID_STATE
QUOTE_ALREADY_SUBMITTED
CATALOG_VERSION_NOT_ACTIVE
PRICE_CALCULATION_FAILED
VALIDATION_FAILED
AUTHENTICATION_REQUIRED
ACCESS_DENIED
TENANT_MISMATCH
DEPENDENCY_TIMEOUT
INTERNAL_ERROR

NULL_POINTER_AT_PRICING_SERVICE
POSTGRES_ERROR_23505_FROM_QUOTE_TABLE
JACKSON_MAPPING_EXCEPTION

- is stable
- is documented
- maps to a category
- maps to support playbook if needed
- does not expose implementation
- can be used by generated clients and UI logic

{
  "errorCode": "QUOTE_INVALID_STATE",
  "message": "Quote cannot be submitted from its current state.",
  "correlationId": "c-123"
}

409 Conflict

HTTP status: the request conflicts with current resource state.
errorCode: specifically quote state transition is invalid.

200 OK
Content-Type: application/json

{
  "success": false,
  "errorCode": "QUOTE_NOT_FOUND"
}

{
  "errorCode": "DEPENDENCY_TIMEOUT",
  "message": "A downstream dependency did not respond in time.",
  "retryable": true,
  "correlationId": "c-123"
}

@Provider
public class QuoteNotFoundExceptionMapper
        implements ExceptionMapper<QuoteNotFoundException> {

    @Override
    public Response toResponse(QuoteNotFoundException exception) {
        ErrorResponse error = new ErrorResponse(
            "QUOTE_NOT_FOUND",
            "Quote was not found.",
            List.of(),
            Correlation.currentId()
        );

        return Response.status(Response.Status.NOT_FOUND)
            .type(MediaType.APPLICATION_JSON)
            .entity(error)
            .build();
    }
}

ExceptionMapper itself can fail.

public abstract class ApplicationException extends RuntimeException {
    private final String errorCode;
    private final boolean retryable;

    protected ApplicationException(String errorCode, String message, boolean retryable) {
        super(message);
        this.errorCode = errorCode;
        this.retryable = retryable;
    }

    public String errorCode() {
        return errorCode;
    }

    public boolean retryable() {
        return retryable;
    }
}

public final class QuoteInvalidStateException extends ApplicationException {
    public QuoteInvalidStateException(String quoteId, String currentState) {
        super(
            "QUOTE_INVALID_STATE",
            "Quote cannot be submitted from its current state.",
            false
        );
    }
}

public final class DependencyTimeoutException extends ApplicationException {
    public DependencyTimeoutException(String dependencyName, Throwable cause) {
        super(
            "DEPENDENCY_TIMEOUT",
            "A downstream dependency did not respond in time.",
            true
        );
        initCause(cause);
    }
}

@Provider
public class ApplicationExceptionMapper
        implements ExceptionMapper<ApplicationException> {

    @Override
    public Response toResponse(ApplicationException exception) {
        ErrorResponse body = ErrorResponse.from(exception, Correlation.currentId());

        Response.Status status = switch (exception.errorCode()) {
            case "QUOTE_NOT_FOUND" -> Response.Status.NOT_FOUND;
            case "QUOTE_INVALID_STATE" -> Response.Status.CONFLICT;
            case "ACCESS_DENIED" -> Response.Status.FORBIDDEN;
            default -> Response.Status.BAD_REQUEST;
        };

        return Response.status(status)
            .type(MediaType.APPLICATION_JSON_TYPE)
            .entity(body)
            .build();
    }
}

Mapping by string errorCode can become messy.

public record ErrorDescriptor(
    String code,
    int httpStatus,
    boolean retryable
) {}

public enum ApiError {
    QUOTE_NOT_FOUND("QUOTE_NOT_FOUND", 404, false),
    QUOTE_INVALID_STATE("QUOTE_INVALID_STATE", 409, false),
    DEPENDENCY_TIMEOUT("DEPENDENCY_TIMEOUT", 503, true);

    public final String code;
    public final int status;
    public final boolean retryable;

    ApiError(String code, int status, boolean retryable) {
        this.code = code;
        this.status = status;
        this.retryable = retryable;
    }
}

{
  "errorCode": "VALIDATION_FAILED",
  "message": "Request validation failed.",
  "details": [
    {
      "field": "customerId",
      "reason": "must not be blank"
    },
    {
      "field": "items[0].quantity",
      "reason": "must be greater than or equal to 1"
    }
  ],
  "correlationId": "c-123"
}

@Provider
public class ConstraintViolationExceptionMapper
        implements ExceptionMapper<ConstraintViolationException> {

    @Override
    public Response toResponse(ConstraintViolationException exception) {
        List<ErrorDetail> details = exception.getConstraintViolations().stream()
            .map(v -> new ErrorDetail(
                normalizePath(v.getPropertyPath().toString()),
                v.getMessage()
            ))
            .toList();

        ErrorResponse body = new ErrorResponse(
            "VALIDATION_FAILED",
            "Request validation failed.",
            details,
            Correlation.currentId()
        );

        return Response.status(Response.Status.BAD_REQUEST)
            .type(MediaType.APPLICATION_JSON)
            .entity(body)
            .build();
    }

    private String normalizePath(String path) {
        return path;
    }
}

Validation messages may be localized, unstable, or leak internal field paths.

{
  "customerId": "C-123",
  "items": [

{
  "errorCode": "MALFORMED_REQUEST_BODY",
  "message": "Request body is not valid JSON.",
  "correlationId": "c-123"
}

- malformed JSON
- invalid date format
- invalid enum
- numeric value out of range
- unknown property if configured as fail-on-unknown

{
  "errorCode": "AUTHENTICATION_REQUIRED",
  "message": "Authentication is required.",
  "correlationId": "c-123"
}

{
  "errorCode": "ACCESS_DENIED",
  "message": "Access denied.",
  "correlationId": "c-123"
}

{
  "errorCode": "ACCESS_DENIED",
  "message": "User does not have QUOTE_APPROVE permission for tenant T-900 in region EU."
}

- Should unauthorized resource access return 403 or 404?
- Should missing token and invalid token have same public message?
- Are auth failures logged as security events?
- Are token validation details redacted?

public final class InvalidQuoteTransitionException extends RuntimeException {
    private final String quoteId;
    private final String fromState;
    private final String attemptedAction;

    public InvalidQuoteTransitionException(String quoteId, String fromState, String attemptedAction) {
        super("Invalid quote transition");
        this.quoteId = quoteId;
        this.fromState = fromState;
        this.attemptedAction = attemptedAction;
    }
}

@Provider
public class InvalidQuoteTransitionExceptionMapper
        implements ExceptionMapper<InvalidQuoteTransitionException> {

    @Override
    public Response toResponse(InvalidQuoteTransitionException exception) {
        ErrorResponse body = new ErrorResponse(
            "QUOTE_INVALID_STATE",
            "Quote cannot perform the requested action from its current state.",
            List.of(),
            Correlation.currentId()
        );

        return Response.status(Response.Status.CONFLICT)
            .type(MediaType.APPLICATION_JSON)
            .entity(body)
            .build();
    }
}

@Provider
public class UnhandledExceptionMapper implements ExceptionMapper<Throwable> {

    private static final Logger log = LoggerFactory.getLogger(UnhandledExceptionMapper.class);

    @Override
    public Response toResponse(Throwable exception) {
        String correlationId = Correlation.currentId();

        log.error("Unhandled exception. correlationId={}", correlationId, exception);

        ErrorResponse body = new ErrorResponse(
            "INTERNAL_ERROR",
            "The request could not be processed.",
            List.of(),
            correlationId
        );

        return Response.status(Response.Status.INTERNAL_SERVER_ERROR)
            .type(MediaType.APPLICATION_JSON)
            .entity(body)
            .build();
    }
}

Mapping Throwable catches a lot. Make sure platform/runtime-specific exceptions are not accidentally hidden from container behavior in a harmful way.

Service A calls Pricing Service.
Pricing Service returns internal error body.
Service A returns exact same body to API client.

- leaks downstream implementation
- changes your public contract based on dependency
- exposes internal service names/details
- creates inconsistent error shape

try {
    return pricingClient.calculatePrice(request);
} catch (PricingTimeoutException ex) {
    throw new DependencyTimeoutException("pricing", ex);
} catch (PricingRejectedException ex) {
    throw new PriceCalculationRejectedException(ex.reasonCode(), ex);
}

{
  "errorCode": "PRICE_CALCULATION_UNAVAILABLE",
  "message": "Price calculation is temporarily unavailable.",
  "retryable": true,
  "correlationId": "c-123"
}

- downstream service name
- downstream status
- downstream error code
- timeout duration
- retry attempts
- trace/span ID

- malformed event
- incompatible schema
- unknown event type
- duplicate event
- out-of-order event
- missing referenced entity
- transient DB failure
- poison message

- stable error code
- retryable classification
- correlation/causation ID
- safe logging
- operational visibility

- correlation ID
- trace ID/span ID
- endpoint/resource method
- tenant ID if allowed and redacted policy permits
- authenticated subject/service identity if allowed
- error code
- exception class
- retryable flag
- dependency name if relevant
- latency
- request size/category, not sensitive body

- tokens
- passwords/secrets
- full request body with PII
- payment/tax sensitive data unless policy allows
- raw customer data in generic technical logs

http_server_errors_total{endpoint="POST /quotes", error_code="QUOTE_INVALID_STATE"}

http_server_errors_total{quote_id="Q-1001", customer_id="C-999999"}

- error rate
- latency SLO burn
- saturation
- dependency outage
- DLQ growth
- failed job count
- customer impact

@Test
void createQuoteReturnsValidationErrorForMissingCustomerId() {
    Response response = target("/quotes")
        .request(MediaType.APPLICATION_JSON)
        .post(Entity.json("{\"items\": []}"));

    assertEquals(400, response.getStatus());

    ErrorResponse error = response.readEntity(ErrorResponse.class);
    assertEquals("VALIDATION_FAILED", error.errorCode());
    assertNotNull(error.correlationId());
}

@Test
void submitQuoteReturnsConflictWhenStateInvalid() {
    Response response = target("/quotes/Q-1001/submission")
        .request(MediaType.APPLICATION_JSON)
        .post(Entity.json("{}"));

    assertEquals(409, response.getStatus());

    ErrorResponse error = response.readEntity(ErrorResponse.class);
    assertEquals("QUOTE_INVALID_STATE", error.errorCode());
}

@Test
void unexpectedErrorDoesNotExposeStackTrace() {
    Response response = target("/test/force-unhandled-error")
        .request(MediaType.APPLICATION_JSON)
        .get();

    assertEquals(500, response.getStatus());

    String body = response.readEntity(String.class);
    assertFalse(body.contains("NullPointerException"));
    assertFalse(body.contains("com.company"));
    assertTrue(body.contains("INTERNAL_ERROR"));
}

- all documented error codes appear in OpenAPI/examples
- all expected validation errors use standard shape
- unknown/unexpected exception maps to safe internal error
- sensitive fields are not present
- correlation ID appears in error response and logs

1. Capture status code, errorCode, correlationId, and timestamp.
2. Find application logs by correlationId/traceId.
3. Determine error class: validation, auth, domain, dependency, technical.
4. Check whether resource method was reached.
5. Check mapper selected for exception.
6. Check whether response body was serialized successfully.
7. Check gateway/proxy logs for status rewriting or timeout.
8. Check downstream dependency logs/traces if dependency error.
9. Check whether retry/circuit breaker/load shedding was involved.
10. Decide whether this is expected client error, product/domain issue, or production incident.

- Did the failure happen before resource method, inside domain logic, or after return during serialization?
- Is the client allowed to retry?
- Did we expose too much or too little information?
- Is this alert-worthy or expected behavior?
- Is this error code documented and tested?

- Is there a clear error class?
- Is HTTP status appropriate?
- Is errorCode stable and documented?
- Is response shape consistent with platform standard?
- Is message safe for external/internal consumer?
- Are sensitive details redacted?
- Is retryability classified correctly?
- Is the exception mapped by a specific mapper?
- Is there a safe fallback mapper?
- Does logging include correlation/trace ID?
- Does telemetry use low-cardinality labels?
- Are validation details useful but not leaky?
- Are auth errors non-enumerating where needed?
- Are downstream errors translated instead of passed through?
- Are tests covering expected and unexpected failures?

- `catch (Exception e) { return 400; }`
- returning `200` with `success=false`
- exposing exception messages directly
- exposing stacktrace/class/package names
- adding new error code without documentation/test
- changing existing error code meaning
- mapping DB unique violation directly to SQL error response
- retrying non-idempotent operation after ambiguous failure

- What is the standard error response shape?
- Is there a central error code catalog?
- Are error codes documented in OpenAPI?
- Are errors based on RFC-style problem detail, custom envelope, or platform standard?
- Which ExceptionMappers are registered?
- Is there a fallback mapper for unexpected exceptions?
- How are validation exceptions mapped?
- How are JSON parse/deserialization errors mapped?
- How are authentication and authorization errors produced: JAX-RS filter, gateway, platform, security library?
- Are domain exceptions distinct from technical exceptions?
- Is retryability represented anywhere?
- Are downstream service errors translated or passed through?
- Does gateway rewrite 4xx/5xx error bodies?
- Are correlation ID and trace ID present in error logs?
- Are auth/security failures sent to security logs/audit trail?
- Are sensitive fields redacted from error response and logs?
- What alert rules exist for 4xx, 5xx, dependency errors, and validation spikes?
- Are known error scenarios covered by tests?
- Are incident runbooks linked to major technical error categories?

- Error handling is contract design plus operational signal design.
- HTTP status is coarse; errorCode is precise.
- Domain, validation, auth, dependency, and technical failures must be separated.
- Client response should be safe and stable; logs/traces should be diagnostic.
- Retryability must be explicit and conservative.
- ExceptionMapper is the key JAX-RS mechanism, but taxonomy is an architecture decision.
- Do not pass through downstream errors blindly.
- Error handling tests are contract tests, not just exception tests.
- Senior review must protect consumers, operators, and security posture at the same time.