HTTP Status Code pada REST API - Perwira Learning Center

1. Client mengirim request yang berisi method (GET, POST, PUT, DELETE, dll.), URL endpoint, headers, dan body (jika ada)
2. Server memproses request sesuai dengan business logic aplikasi
3. Server mengembalikan response yang terdiri dari status line (termasuk response code), headers, dan body

Response code yang dikembalikan bergantung pada kombinasi method HTTP, kondisi resource, validasi input, dan state internal server. Misalnya, POST request yang berhasil membuat resource baru seharusnya mengembalikan 201 Created, bukan sekadar 200 OK.

Cara Client Membaca dan Memanfaatkan Response Code

Client modern—baik browser, mobile app, atau service lain—membaca response code melalui HTTP response header dan menggunakannya untuk:

1. Menentukan flow aplikasi: Redirect ke halaman login jika menerima 401, menampilkan halaman error jika 500
2. Retry logic: Mengulang request secara otomatis untuk error sementara seperti 503 Service Unavailable
3. Caching: Memanfaatkan 304 Not Modified untuk optimasi bandwidth
4. User feedback: Menampilkan pesan error yang sesuai berdasarkan kategori response code

Kategori HTTP Response Code

HTTP Response Code dikelompokkan menjadi lima kategori berdasarkan digit pertama, masing-masing memiliki makna semantik yang berbeda:

1xx – Informational

Response code dalam rentang 100–199 bersifat informasional dan mengindikasikan bahwa request telah diterima dan sedang dalam proses. Kategori ini jarang digunakan dalam REST API modern karena sifatnya yang interim.
Contoh:

• 100 Continue: Server menerima initial request headers dan client dapat melanjutkan mengirim body
• 101 Switching Protocols: Server menyetujui permintaan client untuk beralih protokol (misalnya dari HTTP ke WebSocket)

2xx – Success

Response code 200–299 mengindikasikan bahwa request telah diterima, dipahami, dan diproses dengan sukses oleh server. Ini adalah kategori yang paling diharapkan dalam operasi normal.
Karakteristik:

• Request valid dan berhasil diproses
• Resource berhasil dibuat, diubah, atau dihapus sesuai permintaan
• Client dapat melanjutkan operasi berikutnya

3xx – Redirection

Response code 300–399 menginformasikan bahwa client perlu melakukan tindakan tambahan untuk menyelesaikan request, biasanya berupa redirect ke URL lain.
Contoh:

• 301 Moved Permanently: Resource telah dipindahkan secara permanen ke URL baru
• 302 Found: Redirect sementara ke URL lain
• 304 Not Modified: Resource tidak berubah sejak terakhir diakses (digunakan untuk caching)

4xx – Client Error

Response code 400–499 mengindikasikan bahwa terdapat kesalahan pada request yang dikirim oleh client. Server tidak dapat memproses request karena format, autentikasi, atau otorisasi yang tidak valid.
Karakteristik:

• Kesalahan berasal dari sisi client
• Request perlu diperbaiki sebelum dikirim ulang
• Server tidak akan memproses ulang request yang sama tanpa modifikasi

5xx – Server Error

Response code 500–599 mengindikasikan bahwa server mengalami kesalahan saat memproses request yang sebenarnya valid. Masalah berasal dari sisi server, bukan client.
Karakteristik:

• Request dari client sudah benar
• Server gagal memenuhi request karena masalah internal
• Client dapat mencoba ulang request di waktu yang berbeda

HTTP Response Code yang Paling Sering Digunakan di REST API

A. 200 OK

200 OK adalah response code paling umum yang mengindikasikan bahwa request telah berhasil diproses dan server mengembalikan response sesuai yang diminta.

Kapan Digunakan?

• GET request yang berhasil mengambil data
• PUT request yang berhasil mengupdate resource
• DELETE request yang berhasil menghapus resource dan mengembalikan informasi
• POST request yang memproses data tanpa membuat resource baru

Contoh Kasus: Client melakukan GET request untuk mengambil detail pengguna dengan ID tertentu, dan data ditemukan di database.
Contoh Response JSON:
json

{
"status": "success",
"data": {
               "id": 12345,
               "name": "John Doe",
               "email": "john.doe@example.com",
               "role": "developer"
            }
}

B. 201 Created

201 Created mengindikasikan bahwa request telah berhasil dan menghasilkan pembuatan resource baru di server. Response biasanya menyertakan URI resource yang baru dibuat melalui header Location.

Kapan Digunakan?

• POST request yang berhasil membuat resource baru
• Setelah user registrasi berhasil
• Setelah data baru berhasil disimpan ke database

Contoh Kasus: Client mengirim POST request untuk mendaftarkan pengguna baru, dan server berhasil menyimpan data tersebut.
Contoh Response JSON:

json
{
"status": "success",
"message": "User created successfully",
"data": {
                "id": 12346,
                "name": "Jane Smith",
                "email": "jane.smith@example.com",
                "created_at": "2026-02-07T10:30:00Z"
            }
}

C. 204 No Content

204 No Content mengindikasikan bahwa request berhasil diproses, tetapi server tidak mengembalikan data apapun dalam response body.

Kapan Digunakan?

• DELETE request yang berhasil menghapus resource
• PUT/PATCH request yang hanya mengupdate tanpa perlu mengembalikan data
• Operasi yang sifatnya command tanpa return value

Contoh Kasus: Client mengirim DELETE request untuk menghapus artikel dengan ID tertentu, dan penghapusan berhasil dilakukan.
Contoh Response: Response tidak memiliki body, hanya status code 204 dan headers.

D. 400 Bad Request

400 Bad Request mengindikasikan bahwa server tidak dapat memproses request karena terdapat kesalahan pada syntax, format, atau struktur request yang dikirim client.

Kapan Digunakan?

• Request body tidak sesuai dengan format yang diharapkan (misalnya invalid JSON)
• Parameter wajib tidak disertakan
• Tipe data tidak sesuai dengan yang diharapkan
• Request mengandung karakter atau nilai yang tidak valid

Contoh Kasus: Client mengirim POST request untuk membuat pengguna baru, tetapi field email tidak dalam format yang valid.
Contoh Response JSON:

json
{
"status": "error",
"message": "Bad Request",
"errors": [

                {
                    "field": "email",
                    "message": "Invalid email format"
                }

               ]
}

E. 401 Unauthorized

401 Unauthorized mengindikasikan bahwa request memerlukan autentikasi, tetapi client belum menyediakan credentials yang valid atau credentials yang diberikan tidak valid.

Kapan Digunakan?

• Request tanpa token autentikasi ke endpoint yang protected
• Token autentikasi yang diberikan sudah expired
• Credentials (username/password) yang diberikan salah
• Session user sudah habis

Contoh Kasus: Client mencoba mengakses endpoint /api/profile tanpa menyertakan JWT token dalam header Authorization.
Contoh Response JSON:

json
{
"status": "error",
"message": "Authentication required",
"error_code": "UNAUTHORIZED",
"details": "Please provide a valid authentication token"
}

F. 403 Forbidden

403 Forbidden mengindikasikan bahwa client telah terautentikasi dengan benar, tetapi tidak memiliki permission untuk mengakses resource yang diminta.

Kapan Digunakan?

• User yang terautentikasi mencoba mengakses resource milik user lain
• User dengan role tertentu mencoba mengakses endpoint yang memerlukan role lebih tinggi
• Access control list (ACL) melarang akses ke resource

Contoh Kasus: User dengan role "member" mencoba mengakses endpoint /api/admin/users yang hanya dapat diakses oleh role "admin".
Contoh Response JSON:

json
{
"status": "error",
"message": "Forbidden",
"error_code": "INSUFFICIENT_PERMISSIONS",
"details": "You do not have permission to access this resource"
}

G. 404 Not Found

404 Not Found mengindikasikan bahwa server tidak dapat menemukan resource yang diminta oleh client. Endpoint mungkin valid, tetapi resource dengan identifier tertentu tidak ada.

Kapan Digunakan?

• GET request untuk resource dengan ID yang tidak ada di database
• Endpoint yang tidak terdefinisi dalam routing API
• File atau media yang diminta tidak ditemukan

Contoh Kasus: Client melakukan GET request ke /api/users/99999 tetapi user dengan ID 99999 tidak ada dalam database.
Contoh Response JSON:

json
{
"status": "error",
"message": "Not Found",
"error_code": "RESOURCE_NOT_FOUND",
"details": "User with ID 99999 does not exist"
}

H. 409 Conflict

Arti dan Fungsi: 409 Conflict mengindikasikan bahwa request tidak dapat diselesaikan karena bertentangan dengan state resource saat ini. Biasanya terjadi dalam operasi yang bersifat conditional.

Kapan Digunakan?
Mencoba membuat resource yang sudah ada (duplicate entry)
Update yang menyebabkan konflik dengan constraint database
Concurrent modification yang saling bertentangan
Business rule violation
Contoh Kasus: Client mencoba mendaftarkan pengguna dengan email yang sudah terdaftar dalam sistem.
Contoh Response JSON:

json
{
"status": "error",
"message": "Conflict",
"error_code": "DUPLICATE_ENTRY",
"details": "User with email john.doe@example.com already exists"
}

I. 422 Unprocessable Entity

422 Unprocessable Entity mengindikasikan bahwa server memahami content type dan syntax request sudah benar, tetapi tidak dapat memproses instruksi yang terkandung di dalamnya karena validation error.

Kapan Digunakan?

• Request body valid secara syntax (valid JSON), tetapi gagal validasi business logic
• Field yang dikirim tidak memenuhi constraint (misalnya panjang minimum, format khusus)
• Relasi antar field tidak valid
• Semantic validation error

Contoh Kasus: Client mengirim POST request untuk membuat artikel, tetapi field title kurang dari panjang minimum yang diperlukan.
Contoh Response JSON:

json
{
"status": "error",
"message": "Unprocessable Entity",
"errors": [
                {
"field": "title",
"message": "Title must be at least 10 characters long"
},
{
"field": "publish_date",
"message": "Publish date cannot be in the past"
}
]
}

J. 500 Internal Server Error

500 Internal Server Error mengindikasikan bahwa server mengalami kondisi tidak terduga yang mencegahnya memenuhi request. Ini adalah error generic untuk masalah server yang tidak teridentifikasi.
Kapan Digunakan?

• Unhandled exception dalam aplikasi backend
• Database connection failure
• Third-party service yang tidak merespons
• Bug dalam kode aplikasi
• Resource server yang habis (memory, disk space)

Contoh Kasus: Server mengalami error saat memproses request karena koneksi ke database terputus secara tiba-tiba.
Contoh Response JSON:

json
{
"status": "error",
"message": "Internal Server Error",
"error_code": "INTERNAL_ERROR",
"details": "An unexpected error occurred. Please try again later."
}

Dalam environment production, hindari menampilkan stack trace atau detail internal error kepada client untuk alasan keamanan. Simpan detail error lengkap di server logs untuk debugging.

Best Practice Penggunaan HTTP Response Code

Penggunaan Response Code yang Konsisten

Konsistensi adalah kunci dalam membangun REST API yang mudah dipahami dan digunakan:

1. Gunakan response code yang sesuai dengan operasi: Jangan menggunakan 200 OK untuk semua response. Setiap operasi harus mengembalikan response code yang paling tepat secara semantik.
2. Dokumentasikan mapping response code: Untuk setiap endpoint, dokumentasikan kemungkinan response code yang dapat dikembalikan beserta kondisinya.
3. Konsisten di seluruh API: Jika menggunakan 201 untuk resource creation di satu endpoint, gunakan juga di endpoint lain yang melakukan operasi serupa.
4. Hindari response code yang ambigu: Jangan menggunakan response code yang jarang digunakan atau memiliki interpretasi ganda tanpa dokumentasi yang jelas.

Pemisahan Error Client dan Server

Pemisahan yang jelas antara client error (4xx) dan server error (5xx) sangat penting:

1. 4xx untuk kesalahan client: Gunakan ketika masalah dapat diperbaiki oleh client dengan memodifikasi request (validasi, autentikasi, format).
2. 5xx untuk kesalahan server: Gunakan ketika masalah berada di luar kontrol client dan memerlukan intervensi di sisi server.
3. Jangan gunakan 5xx untuk validation error: Validation error adalah tanggung jawab client, gunakan 400 atau 422.
4. Monitoring dan alerting: Setup alert untuk 5xx errors karena ini mengindikasikan masalah pada infrastruktur atau aplikasi.

Kombinasi Response Code dengan Pesan Error yang Jelas

Response code saja tidak cukup, perlu dikombinasikan dengan response body yang informatif:
Struktur Error Response yang Baik:
json

{
"status": "error",
"message": "Validation failed",
"error_code": "VALIDATION_ERROR",
"errors": [
{
"field": "email",
"message": "Email format is invalid",
"code": "INVALID_FORMAT"
},
{
"field": "password",
"message": "Password must be at least 8 characters",
"code": "MIN_LENGTH"
}
],
"timestamp": "2026-02-07T10:45:30Z",
"path": "/api/users"
}

Elemen yang Sebaiknya Disertakan:

1. status: Indikator sukses atau error
2. message: Pesan error yang human-readable
3. error_code: Kode error unik yang dapat digunakan untuk dokumentasi atau debugging
4. errors/details: Array detail error untuk multiple validation errors
5. timestamp: Waktu terjadinya error untuk correlation dengan logs
6. path: Endpoint yang menghasilkan error

Prinsip Pesan Error:

1. Jelas dan actionable: Beritahu client apa yang salah dan bagaimana memperbaikinya
2. Hindari technical jargon: Gunakan bahasa yang dapat dipahami oleh frontend developer atau end user
3. Jangan expose sensitive information: Hindari menampilkan stack trace, database query, atau internal path dalam production
4. Konsisten dalam format: Gunakan struktur response error yang sama di seluruh API ­

Dampak Penggunaan Response Code yang Benar terhadap Kualitas API

Penggunaan HTTP Response Code yang tepat dan konsisten memberikan dampak positif yang luas:

Dari Perspektif Developer:

• Mengurangi waktu yang dibutuhkan untuk memahami behavior API
• Memudahkan implementasi error handling di sisi client
• Meningkatkan confidence dalam menggunakan API
• Mempercepat proses debugging ketika terjadi masalah

Dari Perspektif Bisnis:

• Meningkatkan kepercayaan partner atau client yang menggunakan API
• Mengurangi support ticket terkait masalah integrasi
• Mempercepat time-to-market untuk fitur baru yang bergantung pada API
• Meningkatkan reputasi produk di komunitas developer

Dari Perspektif Operasional:

• Memudahkan monitoring dan alerting berbasis error rate
• Mempercepat identifikasi root cause masalah production
• Memungkinkan automasi response terhadap jenis error tertentu
• Meningkatkan reliability dan availability sistem secara keseluruhan

Kesimpulan