Kode Status HTTP yang Harus Diketahui Setiap Developer

Kode status HTTP adalah bahasa yang digunakan server untuk memberitahu klien apa yang terjadi dengan suatu request. Setiap developer selalu menemuinya — di DevTools, dalam respons API, di log error, di notifikasi Slack pukul 3 pagi. Mengetahui arti sebenarnya setiap kode, kapan menggunakan kode mana di API-mu sendiri, dan apa yang ditandakan oleh kode umum tentang sebuah bug akan membuatmu jauh lebih cepat dalam debugging dan membangun layanan yang lebih baik.

Kamu bisa mencari kode status HTTP apa pun dengan BrowseryTools HTTP Status Code Reference — gratis, tanpa daftar, semuanya berjalan di browsermu.

Lima Kategori

Kode status adalah angka tiga digit. Digit pertama mendefinisikan kategorinya:

• 1xx — Informasional: Request diterima; pemrosesan berlanjut. Ini jarang ditemukan di sebagian besar aplikasi.
• 2xx — Sukses: Request diterima, dipahami, dan diterima.
• 3xx — Redirection: Tindakan lebih lanjut diperlukan untuk menyelesaikan request. Klien harus mengikuti redirect.
• 4xx — Client Error: Request tidak valid atau tidak diotorisasi. Klien melakukan kesalahan.
• 5xx — Server Error: Server gagal memenuhi request yang valid. Server melakukan kesalahan.

Aturan digit pertama ini penting: jika kamu melihat kode status yang tidak dikenali (seperti 429 atau 451), setidaknya kamu tahu apakah masalahnya ada di sisi klien atau server, dan apakah request akhirnya berhasil.

2xx: Kode Sukses

Kode ini memberitahu klien bahwa request berhasil. Kode spesifik mengkomunikasikan caranya:

• 200 OK — sukses universal. Body respons berisi data yang diminta. Digunakan untuk request GET dan sebagian besar respons yang mengembalikan konten.
• 201 Created — resource baru telah dibuat. Harus menyertakan header Location yang menunjuk ke URL resource baru. Gunakan ini untuk request POST yang membuat record, bukan 200.
• 204 No Content — request berhasil tetapi tidak ada body untuk dikembalikan. Umum untuk request DELETE dan operasi PATCH/PUT di mana klien tidak membutuhkan data yang diperbarui. Respons tidak boleh menyertakan body.
• 206 Partial Content — digunakan dengan range request (header Range). Video player menggunakan ini untuk meminta byte range tertentu dari file media tanpa mengunduh semuanya.

# REST API design pattern
POST   /api/users        → 201 Created  (body: new user object, Location: /api/users/123)
GET    /api/users/123    → 200 OK       (body: user object)
PATCH  /api/users/123    → 200 OK       (body: updated user) or 204 No Content
DELETE /api/users/123    → 204 No Content

3xx: Kode Redirect

Redirect memberitahu klien untuk mencari di tempat lain. Header Location berisi URL baru. Perbedaan utama adalah antara redirect permanen dan sementara, serta antara redirect yang mempertahankan metode HTTP dan yang mengubahnya.

• 301 Moved Permanently — resource memiliki URL permanen baru. Browser dan search engine menyimpannya dalam cache. Browser akan menggunakan GET untuk redirect terlepas dari metode aslinya (keanehan historis). Gunakan ini saat secara permanen mengganti nama URL atau mengalihkan HTTP ke HTTPS.
• 302 Found — redirect sementara. Seperti 301, browser mengubah POST menjadi GET pada redirect. Gunakan 302 hanya ketika redirectnya benar-benar sementara.
• 304 Not Modified — versi cache masih segar; tidak ada body. Server mengirim ini sebagai respons atas conditional GET (dengan If-None-Match atau If-Modified-Since). Browser menggunakan salinan cache-nya. Penting untuk efisiensi CDN dan pengurangan bandwidth.
• 307 Temporary Redirect — seperti 302, tetapi spesifikasi menjamin metode HTTP asli dipertahankan. Jika POST menghasilkan 307, browser akan POST ke URL baru. Gunakan 307 daripada 302 untuk redirect sementara non-GET.
• 308 Permanent Redirect — seperti 301, tetapi juga menjamin preservasi metode. Standar modern untuk redirect permanen.

Kesalahpahaman Umum: 301 vs 302 untuk SEO

Search engine memperlakukan 301 sebagai sinyal untuk mentransfer "ekuitas tautan" (PageRank) dari URL lama ke yang baru dan memperbarui indeks mereka. 302 memberitahu crawler bahwa redirect bersifat sementara, sehingga crawler terus mengindeks URL asli. Menggunakan 302 saat kamu bermaksud 301 dapat menekan manfaat SEO dari redirect. Sebaliknya, menggunakan 301 saat redirect bersifat sementara menyebabkan search engine menyimpan redirect dalam cache, sehingga lebih sulit untuk dibatalkan.

4xx: Kode Client Error

Kode ini menunjukkan klien mengirim request yang buruk. Jangan kembalikan 5xx untuk kesalahan klien — itu menyesatkan monitoring dan mempersulit identifikasi apakah masalahnya adalah bug di servermu atau input buruk dari klien.

• 400 Bad Request — request tidak valid. Field yang diperlukan hilang, JSON tidak valid, tipe data salah. Yang paling generik di 4xx; gunakan kode yang lebih spesifik jika tersedia.
• 401 Unauthorized — meski namanya demikian, ini berarti "tidak diautentikasi." Klien tidak memberikan kredensial, atau kredensialnya tidak valid. Respons harus menyertakan header WWW-Authenticate yang menunjukkan cara autentikasi. Namanya adalah kesalahan historis — "unauthenticated" akan lebih akurat.
• 403 Forbidden — terautentikasi tetapi tidak diotorisasi. Server mengetahui siapa kamu (atau tidak penting siapa kamu) dan kamu tidak memiliki izin. Tidak seperti 401, autentikasi ulang tidak akan membantu. Gunakan 403 ketika pengguna mencoba mengakses resource yang tidak boleh mereka lihat.
• 404 Not Found — resource tidak ada di URL ini. Juga dikembalikan ketika server ingin menyembunyikan keberadaan resource dari pengguna yang tidak diotorisasi (mengembalikan 403 akan mengkonfirmasi resource ada; mengembalikan 404 menyembunyikan fakta itu).
• 409 Conflict — request bertentangan dengan kondisi resource saat ini. Contoh klasik: mencoba membuat pengguna dengan email yang sudah ada, atau mencoba memperbarui resource menggunakan versi yang sudah usang (konflik optimistic locking).
• 422 Unprocessable Entity — request secara sintaksis benar (JSON valid, Content-Type benar) tetapi secara semantik tidak valid (field yang diperlukan ada tetapi berisi nilai yang tidak valid, pelanggaran aturan bisnis). Rails mempopulerkan penggunaan 422 untuk error validasi. Lebih spesifik dari 400.
• 429 Too Many Requests — batas rate terlampaui. Harus menyertakan header Retry-After yang memberitahu klien berapa lama harus menunggu. Penting untuk API publik mana pun.

401 vs 403: Perbedaan yang Penting

Ini adalah salah satu pasangan yang paling sering membingungkan:

GET /api/admin/users
Authorization: (none)
→ 401 Unauthorized
   "You haven't told me who you are. Log in first."

GET /api/admin/users
Authorization: Bearer <valid-regular-user-token>
→ 403 Forbidden
   "I know who you are. You're not an admin. Access denied."

5xx: Kode Server Error

• 500 Internal Server Error — catch-all generik untuk kegagalan server yang tidak terduga. Exception yang tidak tertangani, null reference, query database yang melempar error. Jangan ekspos stack trace ke klien; log di sisi server.
• 502 Bad Gateway — server yang bertindak sebagai proxy atau gateway menerima respons tidak valid dari server upstream. Umum ketika load balancer atau reverse proxy tidak dapat menjangkau server aplikasi di belakangnya — aplikasi crash atau tidak mendengarkan di port yang benar.
• 503 Service Unavailable — server sementara tidak dapat menangani request. Bisa kelebihan beban, sedang dalam proses deployment, atau sedang maintenance. Harus menyertakan header Retry-After ketika durasi pemadaman diketahui.
• 504 Gateway Timeout — proxy atau gateway tidak menerima respons tepat waktu dari server upstream. Upstream berjalan dan merespons, tetapi terlalu lambat. Gejala umum dari query database yang terlalu lama atau panggilan API eksternal yang hang.

Kode Status dalam Desain REST API

Menggunakan kode status yang tepat membuat API-mu mendokumentasikan diri sendiri dan lebih mudah diintegrasikan. Beberapa panduan:

• Jangan pernah mengembalikan 200 dengan objek error di body. Jika request gagal, kode status harus mencerminkan itu. Klien harus bisa memeriksa kode status saja untuk mengetahui apakah mereka perlu menangani error.
• Gunakan 201 dan header Location saat membuat resource melalui POST. Ini memungkinkan klien menemukan URL resource baru tanpa mem-parsing body.
• Kembalikan 422 (bukan 400) untuk error validasi, dan sertakan body error terstruktur yang mengidentifikasi field mana yang gagal dan mengapa.
• Gunakan 409 untuk konflik yang membutuhkan resolusi di level aplikasi, bukan sekadar input buruk.
• Implementasikan 429 dengan rate limiting sejak awal di endpoint apa pun yang menghadap publik — jauh lebih sulit ditambahkan secara retroaktif.

Debugging Kode Status di DevTools

Buka tab Network di DevTools browser dan cari request berwarna merah — itu adalah respons 4xx atau 5xx. Klik request untuk melihat kode status tepatnya, header respons (berguna untuk WWW-Authenticate, Location, Retry-After), dan body respons (yang sering berisi pesan error dari server). Untuk redirect, centang "Preserve log" agar panel DevTools tidak terhapus saat halaman navigasi — jika tidak, kamu akan melewatkan rantai redirect.

Ketika kamu menemukan kode status yang tidak dikenal, BrowseryTools HTTP Status Code Reference memberikan deskripsi resmi, RFC asalnya, dan catatan tentang penggunaan umum — tanpa harus meninggalkan tab browsermu.