Semua error menjadi HTTP 500.
Duplicate request terlihat seperti database failure.
Validation error tidak bisa dibedakan dari authorization error.
Camunda BPMN business rejection menjadi technical incident.
Kafka consumer retry selamanya untuk payload yang memang invalid.
PostgreSQL constraint violation bocor sebagai stack trace.
MyBatis exception langsung dikirim ke client.
Outbox publish failure dianggap business failure.
Dashboard error count naik tetapi tidak menjelaskan apa yang harus dilakukan.

Input error
Domain error
Application error
Authorization error
Conflict/concurrency error
Idempotency error
Infrastructure error
Integration contract error
Process/workflow error
Operational error
Programming bug

Case not found.
Case cannot be escalated from CLOSED.
Actor cannot approve own submitted case.
Duplicate idempotency key.
Evidence file type is not allowed.

Database unavailable.
Kafka broker timeout.
Camunda command context failed.
JSON payload cannot be deserialized because producer sent wrong schema.
NullPointerException due to programming bug.

{
  "message": "Cannot escalate from CLOSED"
}

{
  "type": "https://errors.example.com/case-invalid-state",
  "title": "Case is in an invalid state for this operation",
  "status": 409,
  "code": "CASE_INVALID_STATE",
  "detail": "Case CASE-000000000123 cannot be escalated from CLOSED",
  "correlationId": "corr-abc",
  "retryable": false
}

Siapa yang bisa memperbaiki?

public enum ErrorCode {
    // Input / contract
    REQUEST_BODY_INVALID,
    REQUEST_HEADER_MISSING,
    IDEMPOTENCY_KEY_INVALID,
    EVENT_CONTRACT_INVALID,
    EVENT_VERSION_UNSUPPORTED,

    // Domain / application
    CASE_NOT_FOUND,
    CASE_INVALID_STATE,
    CASE_DUPLICATE_SUBMISSION,
    CASE_VALIDATION_REJECTED,
    EVIDENCE_INVALID,
    DECISION_NOT_ALLOWED,

    // Security
    AUTHENTICATION_REQUIRED,
    AUTHORIZATION_DENIED,

    // Concurrency
    OPTIMISTIC_LOCK_CONFLICT,
    DB_DEADLOCK_RETRYABLE,
    DB_SERIALIZATION_RETRYABLE,

    // Infrastructure
    DATABASE_UNAVAILABLE,
    KAFKA_PUBLISH_FAILED,
    CAMUNDA_COMMAND_FAILED,
    DOWNSTREAM_TIMEOUT,

    // Unknown / bug
    INTERNAL_ERROR,
    PROGRAMMING_INVARIANT_VIOLATED
}

public record ErrorDescriptor(
        ErrorCode code,
        String title,
        int defaultHttpStatus,
        Retryability retryability,
        ErrorOwner owner,
        Visibility visibility
) {}

public enum Retryability {
    NEVER,
    SAFE_TO_RETRY,
    RETRY_AFTER_BACKOFF,
    RETRY_ONLY_IF_IDEMPOTENT,
    OPERATOR_DECISION_REQUIRED
}

public enum ErrorOwner {
    CALLER,
    USER,
    APPLICATION,
    PLATFORM,
    UPSTREAM_PRODUCER,
    DATA_REPAIR,
    ENGINEERING
}

public enum Visibility {
    EXTERNAL_SAFE,
    INTERNAL_ONLY,
    REDACTED
}

public final class ErrorRegistry {
    private static final Map<ErrorCode, ErrorDescriptor> DESCRIPTORS = Map.ofEntries(
            entry(ErrorCode.CASE_NOT_FOUND, new ErrorDescriptor(
                    ErrorCode.CASE_NOT_FOUND,
                    "Case was not found",
                    404,
                    Retryability.NEVER,
                    ErrorOwner.CALLER,
                    Visibility.EXTERNAL_SAFE
            )),
            entry(ErrorCode.CASE_INVALID_STATE, new ErrorDescriptor(
                    ErrorCode.CASE_INVALID_STATE,
                    "Case is in an invalid state for this operation",
                    409,
                    Retryability.NEVER,
                    ErrorOwner.APPLICATION,
                    Visibility.EXTERNAL_SAFE
            )),
            entry(ErrorCode.DATABASE_UNAVAILABLE, new ErrorDescriptor(
                    ErrorCode.DATABASE_UNAVAILABLE,
                    "Database is temporarily unavailable",
                    503,
                    Retryability.RETRY_AFTER_BACKOFF,
                    ErrorOwner.PLATFORM,
                    Visibility.REDACTED
            ))
    );

    public ErrorDescriptor descriptor(ErrorCode code) {
        ErrorDescriptor descriptor = DESCRIPTORS.get(code);
        if (descriptor == null) {
            throw new IllegalStateException("missing error descriptor for " + code);
        }
        return descriptor;
    }
}

public sealed interface CaseDomainError
        permits CaseDomainError.InvalidStateTransition,
                CaseDomainError.EvidenceRejected,
                CaseDomainError.DecisionNotAllowed,
                CaseDomainError.ActorConflict {

    ErrorCode code();
    String safeMessage();

    record InvalidStateTransition(
            CaseId caseId,
            CaseStatus currentState,
            String operation
    ) implements CaseDomainError {
        public ErrorCode code() { return ErrorCode.CASE_INVALID_STATE; }
        public String safeMessage() {
            return "case cannot perform operation in current state";
        }
    }

    record EvidenceRejected(
            EvidenceId evidenceId,
            List<String> reasons
    ) implements CaseDomainError {
        public EvidenceRejected {
            reasons = List.copyOf(reasons);
        }
        public ErrorCode code() { return ErrorCode.EVIDENCE_INVALID; }
        public String safeMessage() { return "evidence is invalid"; }
    }

    record DecisionNotAllowed(
            CaseId caseId,
            ActorId actorId
    ) implements CaseDomainError {
        public ErrorCode code() { return ErrorCode.DECISION_NOT_ALLOWED; }
        public String safeMessage() { return "decision is not allowed"; }
    }

    record ActorConflict(
            ActorId actorId,
            String rule
    ) implements CaseDomainError {
        public ErrorCode code() { return ErrorCode.AUTHORIZATION_DENIED; }
        public String safeMessage() { return "actor violates separation-of-duty rule"; }
    }
}

public sealed interface SubmitCaseResult
        permits SubmitCaseResult.Accepted,
                SubmitCaseResult.Duplicate,
                SubmitCaseResult.Rejected,
                SubmitCaseResult.Failed {

    record Accepted(CaseId caseId, Instant submittedAt) implements SubmitCaseResult {}

    record Duplicate(CaseId existingCaseId) implements SubmitCaseResult {}

    record Rejected(List<ValidationFinding> findings) implements SubmitCaseResult {
        public Rejected {
            findings = List.copyOf(findings);
        }
    }

    record Failed(SubmitCaseApplicationError error) implements SubmitCaseResult {}
}

public sealed interface SubmitCaseApplicationError
        permits SubmitCaseApplicationError.DomainFailure,
                SubmitCaseApplicationError.AuthorizationFailure,
                SubmitCaseApplicationError.TransientFailure,
                SubmitCaseApplicationError.InvariantViolation {

    ErrorCode code();
    Retryability retryability();

    record DomainFailure(CaseDomainError cause) implements SubmitCaseApplicationError {
        public ErrorCode code() { return cause.code(); }
        public Retryability retryability() { return Retryability.NEVER; }
    }

    record AuthorizationFailure(ErrorCode code, ActorId actorId)
            implements SubmitCaseApplicationError {
        public Retryability retryability() { return Retryability.NEVER; }
    }

    record TransientFailure(ErrorCode code, String dependency)
            implements SubmitCaseApplicationError {
        public Retryability retryability() { return Retryability.RETRY_AFTER_BACKOFF; }
    }

    record InvariantViolation(String detail) implements SubmitCaseApplicationError {
        public ErrorCode code() { return ErrorCode.PROGRAMMING_INVARIANT_VIOLATED; }
        public Retryability retryability() { return Retryability.NEVER; }
    }
}

{
  "type": "https://errors.example.com/case-invalid-state",
  "title": "Case is in an invalid state for this operation",
  "status": 409,
  "detail": "The requested operation cannot be performed for the current case state.",
  "instance": "/cases/CASE-000000000123/escalations/req-abc",
  "code": "CASE_INVALID_STATE",
  "correlationId": "corr-abc",
  "retryable": false,
  "owner": "CALLER"
}

@Provider
public final class UnhandledExceptionMapper implements ExceptionMapper<Throwable> {
    private final ErrorRegistry errorRegistry;
    private final ProblemFactory problemFactory;

    @Override
    public Response toResponse(Throwable throwable) {
        ClassifiedError classified = classify(throwable);
        HttpProblem problem = problemFactory.from(classified);

        return Response.status(problem.status())
                .type("application/problem+json")
                .entity(problem)
                .build();
    }
}

public final class SubmitCaseResponseMapper {
    public Response toResponse(SubmitCaseResult result) {
        if (result instanceof SubmitCaseResult.Accepted accepted) {
            return Response.status(201).entity(toResponseBody(accepted)).build();
        }
        if (result instanceof SubmitCaseResult.Duplicate duplicate) {
            return Response.status(200).entity(toDuplicateBody(duplicate)).build();
        }
        if (result instanceof SubmitCaseResult.Rejected rejected) {
            return Response.status(422).entity(toValidationProblem(rejected)).build();
        }
        if (result instanceof SubmitCaseResult.Failed failed) {
            return toProblemResponse(failed.error());
        }
        throw new IllegalStateException("unmapped result " + result.getClass().getName());
    }
}

public record ValidationFinding(
        String path,
        ErrorCode code,
        String message,
        Severity severity
) {
    public ValidationFinding {
        if (path == null || path.isBlank()) throw new IllegalArgumentException("path is required");
        if (code == null) throw new IllegalArgumentException("code is required");
        if (message == null || message.isBlank()) throw new IllegalArgumentException("message is required");
        if (severity == null) throw new IllegalArgumentException("severity is required");
    }
}

public enum Severity {
    ERROR,
    WARNING
}

{
  "type": "https://errors.example.com/case-validation-rejected",
  "title": "Case submission failed validation",
  "status": 422,
  "code": "CASE_VALIDATION_REJECTED",
  "correlationId": "corr-abc",
  "retryable": false,
  "violations": [
    {
      "path": "$.evidence[0].occurredAt",
      "code": "EVIDENCE_INVALID",
      "message": "Evidence occurrence date cannot be in the future"
    }
  ]
}

23505 unique_violation
23503 foreign_key_violation
23514 check_violation
40001 serialization_failure
40P01 deadlock_detected

public final class PostgreSqlErrorTranslator {
    public PersistenceError translate(SQLException exception) {
        String sqlState = exception.getSQLState();

        return switch (sqlState) {
            case "23505" -> new PersistenceError.UniqueViolation(extractConstraint(exception));
            case "23503" -> new PersistenceError.ForeignKeyViolation(extractConstraint(exception));
            case "23514" -> new PersistenceError.CheckViolation(extractConstraint(exception));
            case "40001" -> new PersistenceError.SerializationFailure();
            case "40P01" -> new PersistenceError.DeadlockDetected();
            default -> new PersistenceError.UnknownDatabaseFailure(sqlState);
        };
    }
}

public sealed interface PersistenceError
        permits PersistenceError.UniqueViolation,
                PersistenceError.ForeignKeyViolation,
                PersistenceError.CheckViolation,
                PersistenceError.SerializationFailure,
                PersistenceError.DeadlockDetected,
                PersistenceError.UnknownDatabaseFailure {

    record UniqueViolation(String constraintName) implements PersistenceError {}
    record ForeignKeyViolation(String constraintName) implements PersistenceError {}
    record CheckViolation(String constraintName) implements PersistenceError {}
    record SerializationFailure() implements PersistenceError {}
    record DeadlockDetected() implements PersistenceError {}
    record UnknownDatabaseFailure(String sqlState) implements PersistenceError {}
}

raise exception using
    errcode = 'P0001',
    message = 'case cannot be escalated from current status',
    detail = 'case_id=' || p_case_id,
    hint = 'check case lifecycle state before escalation';

constraint name: chk_case_valid_status
function-specific error message prefix: CASE_INVALID_STATE
SQLSTATE for class + detail for specific code

public ApplicationError translate(PersistenceError error) {
    if (error instanceof PersistenceError.CheckViolation check) {
        return switch (check.constraintName()) {
            case "chk_case_valid_status" -> domain(ErrorCode.CASE_INVALID_STATE);
            case "chk_evidence_valid_type" -> domain(ErrorCode.EVIDENCE_INVALID);
            default -> invariantViolation("unknown check constraint: " + check.constraintName());
        };
    }
    // ...
}

public final class MyBatisCaseRepository implements CaseRepository {
    private final CaseMapper mapper;
    private final PostgreSqlErrorTranslator errorTranslator;

    @Override
    public void insert(CaseRecord record) {
        try {
            mapper.insert(record);
        } catch (PersistenceException exception) {
            throw new RepositoryException(errorTranslator.translate(rootSqlException(exception)), exception);
        }
    }
}

Apakah record ini bisa berhasil jika dicoba ulang?

public sealed interface ConsumerHandlingResult
        permits ConsumerHandlingResult.Handled,
                ConsumerHandlingResult.RetryLater,
                ConsumerHandlingResult.Quarantine,
                ConsumerHandlingResult.StopConsumer {

    record Handled() implements ConsumerHandlingResult {}

    record RetryLater(Duration backoff, String reason) implements ConsumerHandlingResult {}

    record Quarantine(ErrorCode code, String reason) implements ConsumerHandlingResult {}

    record StopConsumer(ErrorCode code, String reason) implements ConsumerHandlingResult {}
}

public ConsumerHandlingResult handle(KafkaRecord<CaseSubmittedV1> record) {
    try {
        HandleCaseSubmittedCommand command = mapper.toCommand(record);
        return service.handle(command);
    } catch (EventContractException contractException) {
        return new ConsumerHandlingResult.Quarantine(
                ErrorCode.EVENT_CONTRACT_INVALID,
                "event contract invalid"
        );
    } catch (RepositoryException repositoryException) {
        return classifyRepositoryFailure(repositoryException);
    } catch (RuntimeException bug) {
        return new ConsumerHandlingResult.StopConsumer(
                ErrorCode.INTERNAL_ERROR,
                "unexpected consumer failure"
        );
    }
}

{
  "originalTopic": "case.events.v1",
  "originalPartition": 4,
  "originalOffset": 912312,
  "originalKey": "CASE-000000000123",
  "consumerGroupId": "case-workflow-correlator",
  "errorCode": "EVENT_CONTRACT_INVALID",
  "errorMessage": "event contract invalid",
  "correlationId": "corr-abc",
  "failedAt": "2026-07-02T10:15:30Z",
  "payloadHash": "sha256:..."
}

Business transaction writes case + audit + outbox atomically.
Kafka publish happens after commit.

business fact sudah durable, publication pending/failed

business command gagal total

public sealed interface PublishAttemptResult
        permits PublishAttemptResult.Published,
                PublishAttemptResult.RetryableFailure,
                PublishAttemptResult.PermanentFailure {

    record Published(String topic, int partition, long offset) implements PublishAttemptResult {}

    record RetryableFailure(ErrorCode code, String reason) implements PublishAttemptResult {}

    record PermanentFailure(ErrorCode code, String reason) implements PublishAttemptResult {}
}

BPMN business error
  -> modeled path
  -> boundary error event / error event subprocess
  -> expected business outcome

Technical exception
  -> failed job retry
  -> possible incident after retries exhausted
  -> operator/engineering attention

Unhandled bug
  -> incident/noise
  -> must be fixed in code

public final class AssessCaseDelegate implements JavaDelegate {
    @Override
    public void execute(DelegateExecution execution) {
        AssessmentResult result = assessmentService.assess(toCommand(execution));

        if (result instanceof AssessmentResult.Rejected rejected) {
            throw new BpmnError(
                    "CASE_ASSESSMENT_REJECTED",
                    rejected.reason()
            );
        }

        if (result instanceof AssessmentResult.Accepted accepted) {
            writeVariables(execution, accepted);
            return;
        }

        throw new IllegalStateException("unmapped assessment result");
    }
}

process instance membutuhkan intervensi atau retry policy exhausted.

try {
    service.perform(command);
} catch (RepositoryException exception) {
    throw new CasePlatformTechnicalException(
            ErrorCode.DATABASE_UNAVAILABLE,
            "database failure during assessment",
            exception
    );
}

Client POST /cases with Idempotency-Key: abc
Server creates case
Network drops before response received
Client retries same request with same key

public sealed interface IdempotencyDecision
        permits IdempotencyDecision.FirstAttempt,
                IdempotencyDecision.ReplayCompleted,
                IdempotencyDecision.ConflictWithDifferentPayload,
                IdempotencyDecision.InProgress {

    record FirstAttempt() implements IdempotencyDecision {}
    record ReplayCompleted(CaseId existingCaseId) implements IdempotencyDecision {}
    record ConflictWithDifferentPayload() implements IdempotencyDecision {}
    record InProgress(Duration retryAfter) implements IdempotencyDecision {}
}

User/action membaca state lama dan mencoba update setelah state berubah.

public record ConcurrencyConflict(
        ErrorCode code,
        String resource,
        String expectedVersion,
        String actualVersion
) {}

errorCode
errorClass
correlationId
requestId
caseId
actorId hash or safe id
processInstanceId
activityId
kafkaTopic
kafkaPartition
kafkaOffset
sqlState
constraintName
retryable
attempt

full access token
raw authorization header
full evidence payload
PII in arbitrary JSON
SQL with interpolated sensitive values
stack trace for expected validation errors at ERROR level

http_requests_total{status, error_code}
application_errors_total{use_case, error_code, retryable}
kafka_consumer_failures_total{topic, group, error_code, action}
kafka_dlq_total{topic, group, error_code}
outbox_publish_failures_total{topic, error_code, retryable}
camunda_delegate_failures_total{process_key, activity_id, error_code}
repository_errors_total{operation, sql_state, constraint}

caseId as metric label -> buruk
error message as label -> buruk
stack trace hash as high-cardinality label -> hati-hati

@Test
void everyErrorCodeHasDescriptor() {
    ErrorRegistry registry = new ErrorRegistry();

    for (ErrorCode code : ErrorCode.values()) {
        assertNotNull(registry.descriptor(code));
    }
}

@Test
void invalidStateMapsTo409() {
    var error = new SubmitCaseApplicationError.DomainFailure(
            new CaseDomainError.InvalidStateTransition(
                    new CaseId("CASE-000000000123"),
                    CaseStatus.CLOSED,
                    "escalate"
            )
    );

    Response response = mapper.toProblemResponse(error);

    assertEquals(409, response.getStatus());
}

@Test
void uniqueViolationMapsToPersistenceUniqueViolation() {
    SQLException sqlException = new SQLException("duplicate", "23505");

    PersistenceError error = translator.translate(sqlException);

    assertInstanceOf(PersistenceError.UniqueViolation.class, error);
}

@Test
void invalidEventContractIsQuarantinedAndNotRetriedForever() {
    ConsumerHandlingResult result = handler.handle(invalidRecord());

    assertInstanceOf(ConsumerHandlingResult.Quarantine.class, result);
}

@Test
void businessRejectionThrowsBpmnError() {
    assertThrows(BpmnError.class, () -> delegate.execute(execution));
}

public record ErrorOperationsGuide(
        ErrorCode code,
        String summary,
        String firstCheck,
        String safeAction,
        String escalationPath
) {}

catch (Exception e) {
    return Response.serverError().build();
}

{
  "error": "org.postgresql.util.PSQLException: ERROR: duplicate key value violates unique constraint..."
}

retry all failures 10 times

any failure = fail immediately

throw new RuntimeException("case rejected")

throw new BpmnError("DATABASE_DOWN")

"case cannot be escalated"

Domain invalid state
  HTTP 409
  Kafka business rejection event
  Camunda BPMN error boundary
  log WARN with error_code=CASE_INVALID_STATE
  metric application_errors_total{error_code=CASE_INVALID_STATE}