Kode Status HTTP Kapan Harus Kembalikan 404 vs 410 vs 301 (dan Berhenti Menebak)

Anda mengembalikan 200 dengan {"error": "user not found"} dalam tubuh. 301 Anda sebenarnya adalah 302. Sumber daya yang dihapus terus mengembalikan 404 selamanya. Mari kita bahas kode status yang sering salah digunakan oleh pengembang, dan apa yang seharusnya dikembalikan.

4xx vs 5xx: Bukan dalam satu kotak yang sama

Pembagian paling mendasar dalam kode status HTTP: 4xx adalah kesalahan klien, 5xx adalah kesalahan Anda. Sederhana dalam teori, tetapi sering dilanggar dalam praktik.

Pelanggaran paling umum: mengembalikan 500 untuk kesalahan validasi. Seorang pengguna mengirimkan JSON yang tidak valid ke API Anda. Itu adalah 400 Permintaan Buruk — data yang dikirim salah. Kode 500 memberi tahu klien “sistem runtuh,” yang memicu peringatan, dicatat sebagai kesalahan server, dan menyebabkan sistem otomatis mencoba ulang (membuat hari buruk Anda lebih buruk). Jika pengguna mengirimkan data yang tidak valid, katakan hal itu dengan kode 4xx.

404 vs 410: Masalah Sumber Daya yang Dihapus

404 Ditemukan berarti: “Saya tidak memiliki itu saat ini, tetapi mungkin coba lagi nanti.” Krawler — termasuk Googlebot — menganggap 404 sebagai sementara. Mereka akan terus memeriksa secara tidak berhenti.

410 Hilang berarti: “Sumber daya ini telah dihapus secara permanen. Berhenti bertanya.” Googlebot menghapus URL 410 dari indeks lebih cepat daripada 404, dan berhenti mengkrawalinya lebih awal. Ini penting untuk SEO dan untuk anggaran krawal di situs besar.

Aturan praktis: jika API Anda menghapus secara permanen sebuah catatan dan tidak akan kembali, kembalikan 410 pada permintaan berikutnya. Alasan satu-satunya untuk memilih 404 untuk sumber daya yang dihapus adalah jika mungkin akan dipulihkan — dengan penghapusan lemah dan jendela pemulihan, posting yang dipublikasikan yang bisa dipublikasikan kembali, dan sebagainya. Jika tidak, 410 lebih jujur dan mesin pencari akan menghargainya.

301 vs 302 (dan Mengapa 307/308 Ada)

301 Dipindahkan Secara Permanen: URL ini telah hilang selamanya, gunakan URL baru tersebut. Browser menyimpan 301 secara agresif. Mesin pencari mentransfer kualitas tautan ke tujuan. Jika Anda menggabungkan domain atau memindahkan situs secara permanen, 301 adalah yang Anda inginkan.

302 Ditemukan: Pergi ke URL lain sementara, tetapi kembali ke URL asli nanti. Tidak ada penyimpanan. Tidak ada transfer kualitas tautan. Gunakan ini untuk arah login, halaman pemeliharaan sementara, atau uji A/B.

Mode kegagalan: menggunakan 302 untuk perpindahan permanen. Anda berpikir “hal yang sama, hanya berbeda,” tetapi mesin pencari tidak mentransfer kualitas tautan melalui 302. Tahun-tahun kerja SEO tetap terikat pada URL lama sementara URL baru tidak berada di ranking. Jika Anda memindahkan sesuatu secara permanen, gunakan 301.

Lalu ada 307 Redirect Sementara dan 308 Redirect Permanen. Ini adalah variasi yang aman terhadap metode: ketika browser mungkin menurunkan POST menjadi GET saat mengikuti 301/302, 307/308 mempertahankan metode asli. Jika Anda memindahkan endpoint API yang menerima badan POST, 307 (sementara) atau 308 (permanen) mempertahankan metode tersebut.

Kode	Jenis	Cache?	Memertahankan metode?	Gunakan untuk
301	Permanen	Ya	Tidak (bisa turun ke GET)	Pindahan situs permanen, penggabungan URL
302	Sementara	TIDAK	Tidak (bisa turun ke GET)	Arah login, ketidakmampuan sementara
307	Sementara	TIDAK	Ya	Arah sementara untuk endpoint POST API
308	Permanen	Ya	Ya	Arah permanen untuk endpoint POST API

401 vs 403: Otentikasi vs Otorisasi

Nama yang membingungkan. 401 Tidak Diperbolehkan sebenarnya berarti tidak terotentikasi — Anda belum login, atau kredensial Anda hilang atau tidak valid. 403 Dilarang berarti Anda telah terotentikasi, tetapi Anda tidak memiliki izin untuk mengakses sumber daya ini.

Perbedaan praktis: 401 harus meminta layar login atau pembaruan token. 403 harus menampilkan pesan izin ditolak. Jika Anda mengembalikan yang salah, klien tidak tahu apakah harus meminta kredensial atau menyerah.

Ada dimensi keamanan juga. Beberapa API mengembalikan 404 alih-alih 403 untuk sumber daya yang tidak dapat diakses oleh pemanggil, untuk menghindari membocorkan bahwa sumber daya tersebut ada. Jika Anda mengembalikan 403 pada sumber daya dari tenant lain, Anda telah mengonfirmasi bahwa sumber daya tersebut ada. Mengembalikan 404 lebih aman secara informasi, meskipun membuat debugging lebih sulit bagi pengguna yang sah. Pilih keputusan yang sesuai dengan model ancaman Anda dan terapkan secara konsisten.

429: Pembatasan Laju, Dengan Header yang Sebenarnya Membantu

Kode 429 yang murni Terlalu Banyak Permintaan sangat mengganggu. 429 dengan header Retry-After sangat berguna.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1746374400

Retry-After dapat berupa jumlah detik atau tanggal HTTP. Klien yang baik akan secara otomatis mengurangi permintaan. Tanpa itu, Anda mengembalikan kode kesalahan dan berharap klien mengetahui kapan harus mencoba kembali — kebanyakan akan langsung menyerang ulang endpoint Anda, yang menghancurkan tujuan pembatasan laju.

Jangan kembalikan 503 untuk pembatasan laju. 503 berarti “layanan tidak tersedia” — infrastruktur down, penyebaran sedang berlangsung, pembatasan jalur terbuka. Pembatasan laju adalah keputusan kebijakan, bukan kegagalan layanan. 429 ada secara khusus untuk hal ini.

Polanya "200 dengan tubuh kesalahan"

Ini terus muncul di API produksi dan perlu berhenti:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "error", "message": "user not found"}

Ini menghancurkan semua yang bergantung pada semantik HTTP. Alat pemantauan melaporkan permintaan sebagai berhasil. Load balancer mengirimkannya melalui. Klien tidak menangkap kesalahan. Log terlihat bersih sementara pengguna melihat kesalahan. Solusinya adalah satu baris: kembalikan kode status yang tepat. 200 berarti berhasil. Jika tidak berhasil, jangan kembalikan 200.

Logika yang sama berlaku untuk 201 vs 200 dalam pembuatan sumber daya. Jika POST ke /users membuat pengguna baru, kembalikan 201 Dibuat dengan Location header yang menunjuk ke sumber daya baru. Kembalikan 200 dan Anda telah melemparkan informasi yang bisa digunakan oleh klien untuk menghindari ronde tambahan.

Skenario API → Kode Status yang Tepat

Berikut adalah tabel referensi untuk skenario yang paling sering muncul dalam pengembangan API REST:

Skenario	Kode status	Catatan
Isi permintaan berbentuk JSON yang tidak valid	400 Permintaan Buruk	Sertakan pesan yang menunjuk ke kesalahan parsing
Field yang hilang atau tidak valid dalam permintaan	422 Entity Tidak Dapat Diproses	422 lebih tepat daripada 400 untuk kegagalan validasi semantik
Token otentikasi hilang atau telah kedaluwarsa	401 Tidak Diperbolehkan	Sertakan WWW-Authenticate header
Terotentikasi tetapi tidak memiliki izin	403 Dilarang	Atau 404 jika menyembunyikan keberadaan sumber daya adalah kebutuhan
Sumber daya tidak ditemukan, mungkin kembalikan	404 Ditemukan	Untuk ketidakhadiran sementara atau sumber daya yang tidak diketahui
Sumber daya dihapus secara permanen	410 Hilang	Krawler akan berhenti memeriksa lebih awal
Membuat sumber daya baru	201 Dibuat	Tambahkan Location: /resources/new-id header
Hapus berhasil, tidak ada tubuh	204 Tidak Ada Isi	Jangan kembalikan objek JSON kosong dengan 200
Perubahan URL secara permanen	301 Dipindahkan Secara Permanen	Mesin pencari mentransfer kualitas tautan
Redirect sementara	302 Ditemukan	Tidak ada penyimpanan, tidak ada transfer kualitas tautan
Mekanisme pembatasan laju telah ditempuh	Terlalu Banyak Permintaan	Selalu sertakan Retry-After
Kecelakaan server yang tidak terduga	500 Kesalahan Server Internal	Jangan bocorkan tumpukan kode dalam tubuh
Ketergantungan atas layanan down	503 Layanan Tidak Tersedia	Tambahkan Retry-After jika waktu hentian terbatas
Redirect POST, pertahankan metode	307 atau 308	307 sementara, 308 permanen

Ketika Anda sedang di tengah PR dan perlu memverifikasi apa artinya kode status aktual, alat Pencarian Kode Status HTTP memberikan definisi spesifikasi, kasus penggunaan umum, dan RFC yang mendefinisikannya.

Memeriksa Rantai Redirect Anda

Setelah migrasi situs atau restrukturisasi URL, perlu memverifikasi rantai redirect penuh — terutama jika Anda memiliki 301 yang kemudian diperbarui untuk menunjuk ke tempat lain, menciptakan rantai multi-hop yang mengalirkan kualitas tautan. Alat Pembaruan Pengontrol mengikuti rantai dan menunjukkan setiap kode status secara berurutan, sehingga Anda dapat memastikan semua hal beres dalam satu langkah.

Anda mungkin juga menyukai