Error Handling Konsisten
dari Domain ke HTTP

Error bukan sekadar pesan gagal, error adalah kontrak lintas layer.

Di backend online shop skincare, error checkout, stok, pembayaran, dan autentikasi harus punya makna yang stabil dari repository sampai HTTP response. Tanpa strategi, setiap layer akan membuat aturannya sendiri dan API kamu jadi tidak bisa ditebak.

Sampai Roadmap 3 kamu sudah sering menulis if err != nil dan, di handler, kamu memanggil httpx.Error(w, http.StatusNotFound, "product_not_found", "...") secara manual di setiap endpoint. Itu bekerja untuk satu domain. Tetapi begitu proyek tumbuh menjadi product, cart, order, inventory, payment, dan promotion, mapping manual ini mulai berulang, tidak konsisten, dan rawan bocor. Satu handler membalas 404, handler lain membalas 500 untuk kasus yang sebenarnya sama.

Chapter ini menjawab tiga pertanyaan yang akan menempel di seluruh proyek: jenis error apa saja yang kita kenal (taksonomi), bagaimana kita menandai dan membungkusnya di service (sentinel dan AppError), dan di mana satu-satunya tempat error diubah menjadi HTTP status (boundary handler terpusat).

Kita memakai package standar Go: errors.New untuk sentinel error, fmt.Errorf dengan verb %w untuk wrapping, serta errors.Is, errors.As, dan errors.Join untuk inspeksi. Rujukan resmi: package errors, fmt.Errorf, dan konstanta status net/http.

Jembatan utama dari JS/React dan PHP/Laravel ke cara berpikir Go.

Sebelum bicara taksonomi, kita luruskan dulu model mentalnya. Inilah perbedaan paling fundamental yang membuat developer JS dan PHP tersandung di Go.

Di JavaScript kamu throw lalu menangkapnya di try/catch. Di Laravel kamu melempar ModelNotFoundException atau ValidationException, lalu framework otomatis memetakannya ke response lewat handler global di app/Exceptions/Handler.php. Pada kedua dunia itu, error adalah aliran kontrol yang bisa melompati banyak fungsi sampai ada yang menangkapnya. Go menolak model itu. Di Go, error adalah nilai biasa yang dikembalikan sebagai return value terakhir, dan caller wajib memutuskan apa yang akan dilakukan dengannya.

Perbandingan bentuk kodeSalin
// JavaScript: gagal lewat throw, tidak terlihat di signature.
async function getProduct(slug) {
  const row = await db.findBySlug(slug);
  if (!row) throw new NotFoundError("product not found"); // melompat ke catch
  return row;
}

// Go: gagal lewat return value, terlihat di signature (Product, error).
func (s *Service) GetProduct(ctx context.Context, slug string) (Product, error) {
	p, err := s.repo.GetBySlug(ctx, s.pool, slug)
	if err != nil {
		return Product{}, err // caller wajib memeriksa err ini
	}
	return p, nil
}

Buat kategori error yang dekat dengan aturan bisnis, bukan dekat dengan detail database.

Domain error adalah bahasa bersama antara service dan handler. Kita butuh kategori yang cukup kecil agar mudah diingat, tetapi cukup ekspresif untuk menggambarkan kasus bisnis utama proyek skincare.

Roadmap menyebut enam kelas error yang harus tercakup: domain error, validation error, not found, unauthorized, conflict, dan internal error. Kita rapikan menjadi lima sentinel kategori plus satu pembeda penting (unauthorized vs forbidden) yang sering tertukar.

Di mana kode error strategy ini tinggal? Sesuai layering Roadmap 4, kategori dan AppError hidup di satu package lintas-domain. Mapping ke HTTP menumpang di internal/httpx yang sudah kita rancang di Roadmap 2, jadi envelope JSON-nya tetap sama dengan seluruh API.

Sentinel error adalah nilai error tetap yang bisa dibandingkan lewat errors.Is.

Sentinel error memberi identitas stabil pada kategori kegagalan. Inilah jangkar yang dipakai handler untuk memutuskan status HTTP, dan dipakai test untuk assert kategori error.

Di Go, sentinel error dibuat sekali dengan errors.New di level package, lalu dibandingkan dengan errors.Is. Jangan bandingkan dengan err == ErrConflict ketika error mungkin sudah di-wrap, karena perbandingan langsung gagal mengenali error yang dibungkus. errors.Is menelusuri seluruh chain.

internal/apperr/apperr.goSalin
package apperr

import (
	"errors"
	"fmt"
)

// Sentinel kategori. Inilah lima identitas yang dikenali boundary HTTP.
var (
	ErrNotFound     = errors.New("not found")
	ErrValidation   = errors.New("validation")
	ErrUnauthorized = errors.New("unauthorized")
	ErrForbidden    = errors.New("forbidden")
	ErrConflict     = errors.New("conflict")
	ErrInternal     = errors.New("internal")
)

Struct memberi metadata tanpa mengorbankan idiom error Go.

Custom error struct membuat error bisa dibaca manusia, dipahami frontend lewat code stabil, dan tetap bisa diinspeksi program. AppError adalah pembawa metadata yang konsisten untuk seluruh proyek.

Sebuah tipe memenuhi interface error ketika punya method Error() string. Pada AppError, kita menambah Kind (sentinel kategori), Code (kontrak frontend, snake_case), Message (pesan aman untuk client), Fields (validasi per field, memakai httpx.FieldError yang sudah ada), dan cause (error asli untuk log internal, tidak diekspos).

internal/apperr/apperr.goSalin
// AppError adalah error domain berstruktur yang membawa kategori dan metadata.
type AppError struct {
	Kind    error              // sentinel: ErrNotFound, ErrConflict, ...
	Code    string             // kode stabil snake_case untuk frontend
	Message string             // pesan aman yang boleh tampil ke user
	Fields  []FieldError       // detail per field, untuk validation error
	cause   error              // error asli, untuk log; tidak pernah ke client
}

// FieldError sengaja sama bentuknya dengan httpx.FieldError, tetapi
// didefinisikan di sini agar apperr tetap bebas dependency ke httpx.
type FieldError struct {
	Field   string
	Message string
}

func (e *AppError) Error() string {
	if e.cause == nil {
		return fmt.Sprintf("%s: %s", e.Code, e.Message)
	}
	return fmt.Sprintf("%s: %s: %v", e.Code, e.Message, e.cause)
}

// Unwrap membuka cause agar errors.Is/As bisa menelusuri error asli.
func (e *AppError) Unwrap() error { return e.cause }

// Is membuat errors.Is(appErr, apperr.ErrConflict) bekerja lewat Kind.
func (e *AppError) Is(target error) bool { return errors.Is(e.Kind, target) }

Constructor membuat pembuatan AppError ringkas dan konsisten. Satu constructor per kategori, plus satu helper untuk validasi yang membawa daftar field.

internal/apperr/apperr.goSalin
func newError(kind error, code, message string, cause error) *AppError {
	return &AppError{Kind: kind, Code: code, Message: message, cause: cause}
}

func NotFound(code, message string, cause error) *AppError {
	return newError(ErrNotFound, code, message, cause)
}

func Unauthorized(code, message string, cause error) *AppError {
	return newError(ErrUnauthorized, code, message, cause)
}

func Forbidden(code, message string, cause error) *AppError {
	return newError(ErrForbidden, code, message, cause)
}

func Conflict(code, message string, cause error) *AppError {
	return newError(ErrConflict, code, message, cause)
}

func Internal(cause error) *AppError {
	// Internal selalu memakai code dan message generik yang aman.
	return newError(ErrInternal, "internal_error", "terjadi kesalahan pada server", cause)
}

// Validation membawa daftar field yang gagal, kompatibel dengan envelope httpx.
func Validation(message string, fields []FieldError) *AppError {
	return &AppError{
		Kind:    ErrValidation,
		Code:    "validation_error",
		Message: message,
		Fields:  fields,
	}
}

Tiga alat standar untuk menginspeksi error tanpa membandingkan string.

Setelah punya sentinel dan struct, kita butuh cara membacanya kembali di handler. Inilah tiga fungsi inti dari package errors yang menggantikan instanceof dan catch (e: SpecificError) dari JS/PHP.

errors.Is(err, target) menelusuri chain error (lewat Unwrap) dan menjawab “apakah err ini, atau salah satu error di dalamnya, sama dengan target?”. Ini cara memeriksa kategori. errors.As(err, &dst) mencari error pertama di chain yang tipenya cocok dengan dst, lalu mengisinya, sehingga kamu bisa membaca field-nya. Ini cara mengambil metadata.

Inspeksi error: Is untuk kategori, As untuk metadataSalin
// Is: apakah error ini termasuk kategori konflik? (untuk status HTTP)
if errors.Is(err, apperr.ErrConflict) {
	// ... balas 409
}

// As: ambil *AppError dari chain untuk membaca Code, Message, Fields.
var appErr *apperr.AppError
if errors.As(err, &appErr) {
	code := appErr.Code        // "out_of_stock"
	message := appErr.Message  // "stok produk tidak cukup"
	fields := appErr.Fields    // detail validasi, jika ada
}

errors.Join menggabungkan beberapa error menjadi satu. Ini berguna saat sebuah operasi punya banyak kegagalan kecil yang ingin dilaporkan sekaligus, misalnya validasi beberapa field tanpa berhenti di yang pertama. errors.Is tetap bisa mengenali tiap error di dalam hasil join.

errors.Join untuk mengumpulkan beberapa kegagalanSalin
func validateAddress(a Address) error {
	var errs []error
	if a.RecipientName == "" {
		errs = append(errs, apperr.Validation("nama penerima wajib diisi", []apperr.FieldError{
			{Field: "recipient_name", Message: "wajib diisi"},
		}))
	}
	if a.PostalCode == "" {
		errs = append(errs, apperr.Validation("kode pos wajib diisi", []apperr.FieldError{
			{Field: "postal_code", Message: "wajib diisi"},
		}))
	}
	// Join mengembalikan nil jika errs kosong, jadi aman dipanggil selalu.
	return errors.Join(errs...)
}

Tambahkan konteks tanpa menghilangkan identitas error asli.

Wrapping membuat log lebih berguna karena membawa jejak operasi, tetapi handler tetap bisa mengenali kategori error. Kuncinya adalah verb %w pada fmt.Errorf.

Saat repository atau service gagal, tambahkan konteks dengan fmt.Errorf("nama operasi: %w", err). Verb %w (wrap) menyimpan error lama di dalam error baru, sehingga errors.Is dan errors.As tetap bisa menelusurinya. Bandingkan dengan %v yang hanya mencetak teks error dan memutus chain, membuat kategori hilang.

Di repository, error pgx diterjemahkan menjadi error domain di perbatasan, bukan diteruskan mentah. Inilah disiplin boundary yang kita mulai di repository pattern Roadmap 3, sekarang dipertegas.

internal/product/repository.goSalin
package product

import (
	"context"
	"errors"
	"fmt"

	"github.com/jackc/pgx/v5"

	"github.com/kamu/skincare-backend/internal/apperr"
	"github.com/kamu/skincare-backend/internal/database"
)

func (r *pgProductRepository) GetByID(ctx context.Context, db database.Querier, id int64) (Product, error) {
	const query = `
		SELECT id, brand_id, slug, name, status, price_rupiah
		FROM product_variants
		WHERE id = $1 AND deleted_at IS NULL`

	var p Product
	err := db.QueryRow(ctx, query, id).Scan(
		&p.ID, &p.BrandID, &p.Slug, &p.Name, &p.Status, &p.PriceRupiah,
	)
	if err != nil {
		if errors.Is(err, pgx.ErrNoRows) {
			// Terjemahkan error pgx jadi error domain di perbatasan.
			return Product{}, apperr.NotFound(
				"product_not_found",
				"produk tidak ditemukan",
				err, // err asli disimpan sebagai cause untuk log, tidak ke client
			)
		}
		// Error teknis lain: wrap dengan konteks operasi, tetap bisa di-unwrap.
		return Product{}, fmt.Errorf("product repository get by id: %w", err)
	}
	return p, nil
}

HTTP status code hanya ditentukan di satu tempat: httpx.WriteError.

Handler adalah satu-satunya tempat error domain diubah menjadi status code dan JSON. Kita tumpangkan mapping ini di internal/httpx agar memakai envelope yang sama dengan seluruh API skincare sejak Roadmap 2.

Service tidak boleh tahu http.StatusConflict, karena service harus tetap bisa dipakai worker, CLI, dan test tanpa membawa konsep HTTP. Yang dilakukan WriteError cukup tiga langkah: cari *AppError di chain (untuk code, message, fields), tentukan status dari Kind lewat errors.Is, lalu untuk kasus 500 ganti dengan pesan generik dan log error aslinya.

internal/httpx/apperror.goSalin
package httpx

import (
	"errors"
	"log/slog"
	"net/http"

	"github.com/kamu/skincare-backend/internal/apperr"
)

// WriteError adalah satu-satunya pintu yang mengubah error jadi HTTP response.
func WriteError(w http.ResponseWriter, logger *slog.Logger, err error) {
	// Default: anggap internal error sampai terbukti sebaliknya.
	status := http.StatusInternalServerError
	code := "internal_error"
	message := "terjadi kesalahan pada server"
	var fields []FieldError

	// Ambil metadata dari AppError jika ada di chain.
	var appErr *apperr.AppError
	if errors.As(err, &appErr) {
		code = appErr.Code
		message = appErr.Message
		fields = toHTTPFields(appErr.Fields)
	}

	// Tentukan status dari kategori (Kind), menelusuri seluruh chain.
	switch {
	case errors.Is(err, apperr.ErrNotFound):
		status = http.StatusNotFound
	case errors.Is(err, apperr.ErrValidation):
		status = http.StatusUnprocessableEntity
	case errors.Is(err, apperr.ErrUnauthorized):
		status = http.StatusUnauthorized
	case errors.Is(err, apperr.ErrForbidden):
		status = http.StatusForbidden
	case errors.Is(err, apperr.ErrConflict):
		status = http.StatusConflict
	}

	// Untuk 500: jangan bocorkan apa pun, log error aslinya secara penuh.
	if status == http.StatusInternalServerError {
		logger.Error("request failed", "error", err)
		Error(w, status, "internal_error", "terjadi kesalahan pada server")
		return
	}

	// Untuk error yang dikenal, kirim envelope yang sama dengan seluruh API.
	JSON(w, status, errEnvelope{
		Error: errBody{Code: code, Message: message, Fields: fields},
	})
}

func toHTTPFields(in []apperr.FieldError) []FieldError {
	if len(in) == 0 {
		return nil
	}
	out := make([]FieldError, 0, len(in))
	for _, f := range in {
		out = append(out, FieldError{Field: f.Field, Message: f.Message})
	}
	return out
}

Dengan boundary terpusat, handler checkout jadi sangat ringkas. Ia tidak lagi menebak status code, cukup meneruskan error ke WriteError.

internal/order/handler.goSalin
package order

import (
	"net/http"

	"github.com/kamu/skincare-backend/internal/httpx"
)

func (h *Handler) Checkout(w http.ResponseWriter, r *http.Request) {
	userID := httpx.UserIDFromContext(r.Context())

	// Ambil isi cart aktif dulu, lalu kirim sebagai items ke service.
	items, err := h.service.CartItems(r.Context(), userID)
	if err != nil {
		httpx.WriteError(w, h.logger, err)
		return
	}

	order, err := h.service.Checkout(r.Context(), userID, items)
	if err != nil {
		httpx.WriteError(w, h.logger, err) // satu baris untuk semua kategori
		return
	}

	httpx.Data(w, http.StatusCreated, NewOrderResponse(order))
}

Error bergerak naik, makna bisnis makin jelas, response dibuat hanya di tepi HTTP.

Diagram ini menunjukkan kenapa error tidak boleh langsung diubah menjadi HTTP response di repository, dan bagaimana kategori dipertahankan sampai boundary.

flowchart LR
  REPO["Repository pgx"] -->|pgx.ErrNoRows / SQL error| TRANS["Translate ke apperr.NotFound"]
  TRANS --> SVC["Service business rule"]
  SVC -->|fmt.Errorf dengan %w| HANDLER["Handler boundary"]
  HANDLER -->|httpx.WriteError| MAP["errors.Is dan errors.As"]
  MAP --> CLIENT["Client JSON envelope"]

  TRANS -.-> NF["ErrNotFound → 404"]
  SVC -.-> CF["ErrConflict → 409"]
  MAP -.-> OUT["code: out_of_stock"]

Gambar 1. Repository tahu detail data, service tahu aturan bisnis, handler tahu HTTP. Kategori error (Kind) terbawa utuh lewat chain %w sampai dipetakan ke status di satu pintu.

Tabel berikut adalah kontrak ringkas yang dipakai seluruh API skincare. Hafalkan kolom kategori dan status, karena inilah yang membuat error predictable lintas domain.

Format response error dibuat stabil agar frontend React dan mobile client tidak perlu menebak dari teks bebas. Inilah bentuk yang dibalas untuk stok kurang.

409 ConflictSalin
{
  "error": {
    "code": "out_of_stock",
    "message": "stok produk tidak cukup"
  }
}

Dan inilah bentuk untuk validasi yang gagal di beberapa field sekaligus.

422 Unprocessable EntitySalin
{
  "error": {
    "code": "validation_error",
    "message": "Validasi gagal",
    "fields": [
      { "field": "recipient_name", "message": "wajib diisi" },
      { "field": "postal_code", "message": "wajib diisi" }
    ]
  }
}

Kasus bisnis nyata: cart valid, varian ada, tetapi stok tidak cukup.

Stok kurang bukan 500, bukan 400 generik, melainkan konflik state bisnis yang tepat menjadi 409. User valid, varian ada, tetapi state sistem menolak operasi karena quantity_available lebih kecil dari yang diminta.

Ingat skema kanonik proyek: stok hidup di tabel inventories, one-to-one dengan product_variants lewat variant_id. Yang ditahan saat checkout adalah quantity_reserved, dengan constraint CHECK (quantity_available >= quantity_reserved). Saat reservasi melebihi stok, operasi gagal, dan inilah momen ErrConflict lahir.

internal/order/service.goSalin
package order

import (
	"context"
	"errors"
	"fmt"

	"github.com/kamu/skincare-backend/internal/apperr"
)

// ErrInsufficientStock adalah sentinel teknis dari layer inventory.
var ErrInsufficientStock = errors.New("insufficient stock")

type InventoryRepository interface {
	// Reserve menahan stok satu varian; mengembalikan ErrInsufficientStock
	// jika quantity_available tidak cukup.
	Reserve(ctx context.Context, variantID int64, quantity int) error
}

func (s *Service) Checkout(ctx context.Context, userID int64, items []CheckoutItem) (*Order, error) {
	if len(items) == 0 {
		return nil, apperr.Validation("keranjang belanja masih kosong", []apperr.FieldError{
			{Field: "items", Message: "minimal satu item"},
		})
	}

	for _, item := range items {
		err := s.inventoryRepo.Reserve(ctx, item.VariantID, item.Quantity)
		if err != nil {
			if errors.Is(err, ErrInsufficientStock) {
				// Stok kurang adalah konflik state: ubah jadi ErrConflict (409).
				return nil, fmt.Errorf("checkout reserve stock: %w", apperr.Conflict(
					"out_of_stock",
					"stok produk tidak cukup",
					err, // cause untuk log, tidak ke client
				))
			}
			// Kegagalan teknis lain tetap dibungkus konteks, jadi 500.
			return nil, fmt.Errorf("checkout reserve stock: %w", err)
		}
	}

	order, err := s.orderRepo.Create(ctx, userID, items)
	if err != nil {
		return nil, fmt.Errorf("checkout create order: %w", err)
	}
	return order, nil
}

Perhatikan dua hal yang menjaga idiom Go tetap rapi. Pertama, ctx selalu menjadi parameter pertama, sehingga timeout request dan cancellation terus terbawa sampai query reservasi stok. Kedua, sentinel teknis ErrInsufficientStock milik layer inventory tidak pernah keluar mentah ke handler. Service menerjemahkannya menjadi apperr.Conflict dengan code stabil out_of_stock, lalu membungkusnya dengan konteks operasi.

Tidak semua conflict soal stok; transisi status yang ilegal juga 409.

Kategori ErrConflict punya teman penting di proyek skincare: transisi status order yang ilegal. Membatalkan order yang sudah dikirim, atau membayar order yang sudah dibayar, adalah operasi valid secara request tetapi ditolak oleh state, persis definisi 409.

Skema orders.status dijaga CHECK dengan nilai: pending, paid, processing, shipped, completed, cancelled. Aturan transisinya adalah aturan bisnis murni, jadi ia tinggal di service, bukan di database dan bukan di handler.

stateDiagram-v2
  [*] --> pending: order dibuat
  pending --> paid: pembayaran sukses
  pending --> cancelled: dibatalkan user / timeout
  paid --> processing: gudang mulai siapkan
  processing --> shipped: kurir ambil paket
  shipped --> completed: diterima pembeli
  paid --> cancelled: refund sebelum diproses

Gambar 2. Transisi status order yang sah. Setiap panah yang tidak ada di diagram (misalnya shipped → cancelled) adalah transisi ilegal yang harus dibalas 409, bukan 500.

Service memvalidasi transisi sebelum menulis ke database. Jika transisi ilegal, ia mengembalikan apperr.Conflict dengan code yang menjelaskan keadaan, sehingga frontend bisa menonaktifkan tombol yang tidak relevan.

internal/order/service.goSalin
// allowedTransitions memetakan status sekarang ke status berikutnya yang sah.
var allowedTransitions = map[string][]string{
	"pending":    {"paid", "cancelled"},
	"paid":       {"processing", "cancelled"},
	"processing": {"shipped"},
	"shipped":    {"completed"},
}

func canTransition(from, to string) bool {
	for _, next := range allowedTransitions[from] {
		if next == to {
			return true
		}
	}
	return false
}

func (s *Service) Cancel(ctx context.Context, orderID int64) error {
	order, err := s.orderRepo.GetByID(ctx, s.pool, orderID)
	if err != nil {
		// GetByID sudah menerjemahkan pgx.ErrNoRows jadi apperr.NotFound (404).
		return fmt.Errorf("cancel get order: %w", err)
	}

	if !canTransition(order.Status, "cancelled") {
		return apperr.Conflict(
			"order_not_cancellable",
			"order pada status ini tidak bisa dibatalkan",
			nil,
		)
	}

	if err := s.orderRepo.UpdateStatus(ctx, s.pool, orderID, "cancelled"); err != nil {
		return fmt.Errorf("cancel update status: %w", err)
	}
	return nil
}

Tambahkan error strategy ke proyek skincare secara bertahap.

Target hands-on ini adalah membuat error checkout, product detail, dan pembatalan order punya response yang konsisten lewat satu boundary terpusat.

Jalankan pemeriksaan cepat dari terminal untuk membuktikan boundary tetap bersih dan package terformat.

TerminalSalin
# Service tidak boleh tahu HTTP
grep -rn "net/http" internal/order/service.go internal/product/service.go

# pgx tidak boleh bocor ke service
grep -rn "jackc/pgx" internal/order/service.go internal/product/service.go

# Format dan jalankan test
gofmt -w internal/apperr internal/httpx internal/product internal/order
go test ./...

Kalau dua grep pertama tidak menghasilkan baris apa pun dan go test lulus, error strategy-mu sudah bersih dan boundary tetap terjaga.

Pendatang dari JS, PHP, dan framework full-stack biasanya tersandung di titik ini.

Error handling Go terasa sederhana, tetapi mudah menjadi berantakan jika tiap layer membuat aturan sendiri. Ini daftar jebakan yang paling sering muncul.

Error strategy menyatukan bahasa domain, debugging internal, dan kontrak HTTP client. Dengan satu taksonomi, satu pembawa metadata, dan satu boundary, error proyek skincare jadi predictable dan aman.

Pola ini menjadi standar untuk product, cart, order, inventory, payment, shipment, dan promotion. Langkah berikutnya di Roadmap 4 adalah Logging Strategy (chapter 5), yang membaca chain error ini secara aman dan berguna untuk production: request ID, user ID, dan konteks error tanpa membocorkan data sensitif. Setelah itu, Validation and Business Rules (chapter 6) memperdalam ErrValidation dengan aturan input dan aturan bisnis yang lebih kaya.

Rujukan resmi yang relevan: package errors, fmt.Errorf dan verb %w, konstanta status net/http, dan log/slog.