RFC 9457: Panduan Cara API Mengembalikan Error yang Benar

Singkatnya

RFC 9457 (Problem Details for HTTP APIs) adalah format standar untuk respons kesalahan API. Ini menggantikan format kesalahan kustom dengan struktur yang konsisten: type, title, status, detail, dan instance. Modern PetstoreAPI mengimplementasikan RFC 9457 di seluruh respons kesalahan dengan negosiasi konten dan detail validasi yang tepat.

Pengantar

API Anda mengembalikan kesalahan. Seperti apa responsnya? Jika Anda seperti kebanyakan API, Anda membuat format Anda sendiri:

{"error": "Invalid email"}
{"message": "Not found", "code": 404}
{"success": false, "errors": ["Email required"]}

Setiap API memiliki format kesalahan yang berbeda. Klien memerlukan penanganan kesalahan kustom untuk setiap API. Tidak ada cara standar untuk mengurai kesalahan, menampilkannya kepada pengguna, atau mencatatnya untuk debug.

RFC 9457 menyelesaikan masalah ini. Ini adalah standar IETF yang mendefinisikan bagaimana API harus mengembalikan kesalahan. Alih-alih membuat format Anda sendiri, Anda menggunakan standar yang terbukti yang sudah dipahami oleh klien.

Swagger Petstore yang lama menggunakan format kesalahan kustom tanpa konsistensi. Modern PetstoreAPI mengimplementasikan RFC 9457 di seluruh respons kesalahan, menyediakan detail kesalahan yang terstruktur dan dapat dibaca mesin.

💡

Jika Anda membangun atau menguji REST API, Apidog membantu Anda memvalidasi respons kesalahan, menguji kepatuhan RFC 9457, dan memastikan API Anda mengembalikan struktur kesalahan yang tepat. Anda dapat menentukan format kesalahan yang diharapkan, menjalankan pengujian otomatis, dan menangkap respons yang salah.

button

Dalam panduan ini, Anda akan mempelajari apa itu RFC 9457, cara mengimplementasikannya dengan benar, dan bagaimana Modern PetstoreAPI menggunakannya untuk semua respons kesalahan.

Masalah Kesalahan API

Sebelum RFC 9457, setiap API membuat format kesalahannya sendiri.

Variasi Format Kesalahan Umum

Format 1: Pesan sederhana

{"error": "User not found"}

Format 2: Kode dan pesan

{"code": "USER_NOT_FOUND", "message": "User not found"}

Format 3: Struktur bersarang

{
  "success": false,
  "error": {
    "type": "NotFound",
    "message": "User not found"
  }
}

Format 4: Larik kesalahan

{
  "errors": [
    {"field": "email", "message": "Invalid email"}
  ]
}

Masalah dengan Format Kustom

1. Tidak ada konsistensi: Klien memerlukan penguraian kustom untuk setiap API.

2. Informasi hilang: Beberapa format kekurangan kode kesalahan, beberapa kekurangan detail, beberapa kekurangan keduanya.

3. Tidak ada struktur yang dapat dibaca mesin: Sulit untuk menangani kesalahan secara terprogram.

4. Internasionalisasi yang buruk: Pesan kesalahan dikodekan secara baku dalam bahasa Inggris.

5. Tidak ada standar untuk kesalahan validasi: Setiap API menangani kesalahan tingkat bidang secara berbeda.

Apa Itu RFC 9457?

RFC 9457 (diterbitkan Juli 2023) mendefinisikan "Problem Details for HTTP APIs." Ini adalah standar IETF yang menentukan bagaimana API harus menyusun respons kesalahan.

Fitur Utama

Tipe media standar: application/problem+json (atau application/problem+xml)
Struktur yang konsisten: Semua kesalahan mengikuti format yang sama
Dapat dibaca mesin: Klien dapat mengurai kesalahan secara terprogram
Dapat diperluas: Anda dapat menambahkan bidang kustom sambil mempertahankan kompatibilitas
Sadar HTTP: Terintegrasi dengan kode status HTTP

RFC 9457 vs Kesalahan Kustom

Kesalahan kustom:

{"error": "Email is required"}

Kesalahan RFC 9457:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid data",
  "instance": "/pets",
  "errors": [
    {
      "field": "email",
      "message": "Email is required"
    }
  ]
}

Versi RFC 9457 menyediakan:

URL tipe kesalahan untuk dokumentasi
Judul yang mudah dibaca manusia
Kode status HTTP
Penjelasan terperinci
Jalur permintaan yang menyebabkan kesalahan
Detail validasi tingkat bidang

Struktur RFC 9457 Dijelaskan

RFC 9457 mendefinisikan lima bidang standar dan memungkinkan ekstensi kustom.

Bidang Standar

1. type (string, wajib)

Referensi URI yang mengidentifikasi tipe kesalahan. Seharusnya menunjuk ke dokumentasi yang mudah dibaca manusia.

"type": "https://petstoreapi.com/errors/validation-error"

Jika dihilangkan, akan menggunakan nilai default about:blank.

2. title (string, wajib)

Ringkasan singkat, mudah dibaca manusia tentang tipe kesalahan. Seharusnya tidak berubah antar kemunculan.

"title": "Validation Error"

3. status (angka, wajib)

Kode status HTTP. Disertakan untuk kemudahan agar klien tidak perlu mengurai header.

"status": 400

4. detail (string, opsional)

Penjelasan yang mudah dibaca manusia yang spesifik untuk kemunculan kesalahan ini.

"detail": "The email field must be a valid email address"

5. instance (string, opsional)

Referensi URI yang mengidentifikasi kemunculan spesifik kesalahan. Seringkali berupa jalur permintaan.

"instance": "/pets/019b4132-70aa-764f-b315-e2803d882a24"

Ekstensi Kustom

Anda dapat menambahkan bidang kustom untuk konteks tambahan:

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute",
  "instance": "/pets",
  "retryAfter": 42,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2026-03-13T10:30:00Z"
}

Bagaimana Modern PetstoreAPI Mengimplementasikan RFC 9457

Modern PetstoreAPI menggunakan RFC 9457 untuk semua respons kesalahan.

Contoh 1: Sumber Daya Tidak Ditemukan

GET /pets/invalid-id
404 Not Found
Content-Type: application/problem+json

{
  "type": "https://docs.petstoreapi.com/errors/not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "The requested pet does not exist",
  "instance": "/pets/invalid-id"
}

Contoh 2: Kesalahan Autentikasi

GET /pets
401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://docs.petstoreapi.com/errors/unauthorized",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Valid authentication credentials are required to access this resource",
  "instance": "/pets"
}

Contoh 3: Batas Tarif Terlampaui

GET /pets
429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60

{
  "type": "https://docs.petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit of 100 requests per minute",
  "instance": "/pets",
  "limit": 100,
  "remaining": 0,
  "resetAt": "2026-03-13T10:31:00Z"
}

Lihat dokumentasi penanganan kesalahan Modern PetstoreAPI untuk semua jenis kesalahan.

Kesalahan Validasi dengan RFC 9457

Kesalahan validasi memerlukan detail tingkat bidang. RFC 9457 memungkinkan ekstensi kustom untuk ini.

Format Validasi Modern PetstoreAPI

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://docs.petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains 2 validation errors",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "species",
      "message": "Species must be one of: DOG, CAT, BIRD, FISH, REPTILE, OTHER",
      "code": "INVALID_ENUM_VALUE",
      "rejectedValue": "DRAGON"
    }
  ]
}

Poin-Poin Penting

array `errors`: Berisi detail validasi tingkat bidang
`field`: Jalur JSON ke bidang yang tidak valid
`message`: Pesan kesalahan yang mudah dibaca manusia
`code`: Kode kesalahan yang dapat dibaca mesin
`rejectedValue`: Nilai yang ditolak (opsional)

Format ini memungkinkan klien untuk:

Menampilkan kesalahan tingkat bidang dalam formulir
Menyoroti bidang yang tidak valid
Memberikan pesan kesalahan spesifik
Menangani kesalahan secara terprogram

Menguji Respons Kesalahan dengan Apidog

Apidog membantu Anda menguji kepatuhan RFC 9457.

Kasus Uji: Kesalahan Validasi

// Apidog test script
pm.test("Returns RFC 9457 error format", () => {
  const response = pm.response.json();

  // Check required fields
  pm.expect(response).to.have.property("type");
  pm.expect(response).to.have.property("title");
  pm.expect(response).to.have.property("status");

  // Check status matches HTTP status
  pm.expect(response.status).to.equal(pm.response.code);

  // Check content type
  pm.expect(pm.response.headers.get("Content-Type"))
    .to.include("application/problem+json");
});

pm.test("Validation errors include field details", () => {
  const response = pm.response.json();

  pm.expect(response).to.have.property("errors");
  pm.expect(response.errors).to.be.an("array");

  response.errors.forEach(error => {
    pm.expect(error).to.have.property("field");
    pm.expect(error).to.have.property("message");
  });
});

Kasus Uji: URL Tipe Kesalahan

pm.test("Error type URL is accessible", async () => {
  const response = pm.response.json();
  const typeUrl = response.type;

  // Verify type URL returns documentation
  const docResponse = await pm.sendRequest(typeUrl);
  pm.expect(docResponse.code).to.equal(200);
});

Migrasi dari Format Kesalahan Kustom

Jika Anda menggunakan format kesalahan kustom, berikut adalah cara bermigrasi ke RFC 9457.

Langkah 1: Tambahkan Header Content-Type

Mulai mengembalikan application/problem+json:

Content-Type: application/problem+json

Langkah 2: Petakan Bidang yang Ada

Petakan format kustom Anda ke RFC 9457:

Sebelum:

{
  "error": "USER_NOT_FOUND",
  "message": "User not found"
}

Sesudah:

{
  "type": "https://api.example.com/errors/user-not-found",
  "title": "User Not Found",
  "status": 404,
  "detail": "User not found"
}

Langkah 3: Dukung Kedua Format (Periode Transisi)

Gunakan negosiasi konten untuk mendukung kedua format:

Accept: application/json → Mengembalikan format kustom
Accept: application/problem+json → Mengembalikan format RFC 9457

Langkah 4: Depresiasi Format Kustom

Setelah klien bermigrasi, depresiasi format kustom dan kembalikan RFC 9457 secara default.

Kesimpulan

RFC 9457 menyediakan format standar untuk respons kesalahan API. Ini menggantikan format kesalahan kustom dengan struktur yang konsisten dan dapat dibaca mesin yang dapat diurai oleh klien secara terprogram.

Modern PetstoreAPI mengimplementasikan RFC 9457 di seluruh respons kesalahan, menunjukkan cara menyusun kesalahan dengan benar dengan detail validasi yang tepat, URL tipe kesalahan, dan kode status HTTP.

Gunakan Apidog untuk menguji kepatuhan RFC 9457, memvalidasi struktur kesalahan, dan memastikan API Anda mengembalikan respons kesalahan yang tepat.

FAQ

Apakah RFC 9457 wajib untuk REST API?

Tidak, tetapi ini adalah standar yang direkomendasikan. Menggunakan RFC 9457 membuat API Anda lebih konsisten dan lebih mudah untuk diintegrasikan oleh klien.

Bisakah saya menggunakan RFC 9457 dengan XML?

Ya, RFC 9457 mendefinisikan format JSON (application/problem+json) dan XML (application/problem+xml).

Haruskah saya selalu menyertakan kelima bidang standar?

type, title, dan status adalah wajib. detail dan instance bersifat opsional tetapi direkomendasikan untuk konteks kesalahan yang lebih baik.

Bisakah saya menambahkan bidang kustom ke respons RFC 9457?

Ya, RFC 9457 dapat diperluas. Anda dapat menambahkan bidang kustom seperti errors, retryAfter, atau traceId untuk konteks tambahan.

Bagaimana saya menangani kesalahan validasi dengan RFC 9457?

Tambahkan array errors kustom dengan detail tingkat bidang. Modern PetstoreAPI menunjukkan pola ini dalam respons kesalahan validasinya.

Ke mana seharusnya URL tipe kesalahan menunjuk?

Seharusnya menunjuk ke dokumentasi yang mudah dibaca manusia yang menjelaskan jenis kesalahan, kemungkinan penyebab, dan cara memperbaikinya.

Apakah saya perlu mengubah kode status HTTP saat menggunakan RFC 9457?

Tidak, RFC 9457 bekerja dengan kode status HTTP standar. Bidang status dalam respons harus cocok dengan kode status HTTP.

Bagaimana cara menguji kepatuhan RFC 9457?

Gunakan Apidog untuk memvalidasi struktur respons kesalahan, memeriksa bidang yang wajib, dan memverifikasi tipe konten yang sesuai dengan spesifikasi RFC 9457.