Desain Error API untuk Agen AI: Error yang Bisa Dipulihkan

Rancang Respons Error API yang Bisa Ditindaklanjuti Agen AI

API Anda mengembalikan 400 Bad Request dengan badan {"error": "invalid input"}. Pengembang manusia biasanya membuka dokumentasi, menemukan bidang yang hilang, lalu memperbaiki payload dalam satu menit. Agen AI tidak bisa menebak: tanpa informasi dan tindakan yang jelas, agen hanya akan mengirim ulang permintaan yang sama, lalu menyimpulkan API Anda rusak.

Coba Apidog hari ini

Respons error adalah bagian API yang paling sering diandalkan agen, tetapi sering paling sedikit dirancang dan diuji. Error yang baik memberi tahu pemanggil:

1. Apa yang salah.
2. Apakah percobaan ulang dapat membantu.
3. Apa yang harus diubah sebelum mencoba lagi.

Postingan tentang pemulihan kesalahan agen AI membahas sisi klien—retry, backoff, dan circuit breaker. Artikel ini berfokus pada sisi API: respons apa yang harus Anda kembalikan agar mekanisme tersebut bekerja.

Dengan Apidog, Anda dapat mendefinisikan respons error dalam spesifikasi, membuat mock, dan mengujinya bersama happy path.

Tiga pertanyaan yang wajib dijawab setiap error

Setiap respons error harus memungkinkan agen menjawab tiga pertanyaan tanpa menebak.

1. Apakah kesalahan ada di sisi klien atau server?

Gunakan status HTTP secara benar:

• 4xx: permintaan bermasalah; mengulang payload yang sama kemungkinan akan gagal lagi.
• 5xx: masalah berada di server; permintaan yang sama mungkin berhasil nanti.

Tanpa perbedaan ini, agen dapat retry tanpa henti pada error validasi atau justru berhenti saat terjadi gangguan sementara.

2. Haruskah agen mencoba lagi, dan kapan?

Tidak semua error 4xx harus langsung dihentikan:

• 429 Too Many Requests: retry setelah menunggu.
• 409 Conflict: mungkin retry setelah membaca ulang state.
• 422 Unprocessable Content: ubah payload terlebih dahulu.
• 401 Unauthorized: biasanya berhenti; menunggu tidak memperbaiki token yang salah.

Nyatakan keputusan ini secara eksplisit, bukan hanya melalui kode status.

3. Apa yang harus diubah?

Pesan seperti "Validation failed" tidak cukup. Berikan instruksi yang dapat diterapkan:

Bidang customer.postal_code wajib diisi ketika country adalah US.

Dengan informasi tersebut, agen dapat memperbaiki payload pada percobaan berikutnya.

Gunakan format error terstruktur

Jangan membuat bentuk error berbeda untuk setiap endpoint. Gunakan RFC 9457: Problem Details for HTTP APIs sebagai dasar, lalu tambahkan field yang membantu agen.

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "The field 'customer.postal_code' is required when 'country' is 'US'.",
  "instance": "/v1/orders",
  "errors": [
    {
      "field": "customer.postal_code",
      "code": "required_conditional",
      "message": "Required when country is US. Provide a 5-digit or 9-digit US postal code.",
      "example": "94107"
    }
  ],
  "retryable": false,
  "next_action": "Add customer.postal_code to the request body and send again."
}

Empat field berikut paling penting untuk agen:

Field	Tujuan
detail	Jelaskan kondisi spesifik yang gagal, bukan kategori umum.
errors	Berikan satu entri per masalah dan sertakan path field yang dapat dipetakan kembali ke payload.
retryable	Boolean eksplisit; jangan memaksa agen menyimpulkannya dari kode status.
next_action	Instruksi langsung tentang tindakan berikutnya.

Kembalikan semua kegagalan validasi sekaligus. Jika API hanya mengembalikan satu error pada setiap request, agen harus melakukan banyak putaran perbaikan yang sebenarnya bisa diselesaikan dalam satu kali retry.

Panduan Google API error design guide juga mendorong penggunaan detail error terstruktur daripada narasi yang tidak konsisten.

Beri tahu kapan agen boleh kembali

Untuk error sementara, berikan waktu tunggu yang jelas. Agen yang tahu harus menunggu 30 detik akan menunggu 30 detik; agen yang tidak tahu cenderung retry terlalu cepat.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have used 1000 of 1000 requests in the current minute window.",
  "retryable": true,
  "retry_after_seconds": 30,
  "next_action": "Wait 30 seconds before sending this request again. Do not retry sooner."
}

Kirim penundaan pada dua tempat:

• Header Retry-After untuk klien HTTP standar.
• retry_after_seconds di body untuk agen dan model.

Pola ini juga berlaku untuk 503 Service Unavailable selama pemeliharaan serta 409 Conflict pada resource yang sedang terkunci.

Untuk implementasi lebih lanjut, lihat panduan rate limit terlampaui dan cara mengimplementasikan pembatasan laju API.

Jangan bocorkan internal, tetapi jangan pernah mengembalikan body kosong

Dua kegagalan umum berada di sisi ekstrem yang berlawanan:

1. Stack trace atau exception internal
   
   Ini dapat membocorkan versi framework, path file, query, atau data sensitif. Selain masalah keamanan, teks panjang tersebut membuang context window agen. Terapkan praktik dari panduan menguji API terhadap input yang tidak tepercaya.

2. Error tanpa informasi
   
   Contohnya 500 tanpa body atau hanya {"error": true}. Agen tidak memiliki dasar untuk memilih antara retry atau berhenti.

Gunakan respons error publik yang stabil disertai ID korelasi:

{
  "type": "https://api.example.com/errors/internal",
  "title": "Internal error",
  "status": 500,
  "detail": "The order could not be created due to an internal error. No order was created.",
  "retryable": true,
  "retry_after_seconds": 5,
  "request_id": "req_01J8ZK3M2Q",
  "next_action": "Retry once after 5 seconds. If it fails again, stop and report request_id req_01J8ZK3M2Q."
}

Kalimat “No order was created” sangat penting untuk endpoint tulis. Tanpanya, agen tidak tahu apakah retry akan membuat duplikasi.

Jika Anda tidak dapat menjamin hasil operasi sebelumnya, gunakan operasi idempoten dan dokumentasikan perilakunya. Lihat panduan kunci idempotensi untuk agen AI.

Sertakan request_id agar manusia dapat menelusuri error ke log. Pastikan ID itu benar-benar dapat dicari dengan mengikuti praktik dalam panduan observabilitas API.

Dokumentasikan error di OpenAPI

Jika respons error tidak ada di dokumen OpenAPI, respons itu tidak tersedia bagi generated client, mock server, maupun alat agen.

responses:
  '201':
    description: Order created
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Order'

  '422':
    description: >
      Validation failed. Not retryable without changing the request body.
      The errors array names each invalid field.
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/Problem'

  '429':
    description: >
      Rate limited. Retryable. Wait for retry_after_seconds before sending again.
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/Problem'

Deskripsi respons bukan sekadar dekorasi. Saat Anda mengubah spesifikasi OpenAPI menjadi tool agen, teks itu menjelaskan perilaku gagal kepada model. Baca panduan mengubah spesifikasi OpenAPI menjadi alat agen untuk konteks implementasinya.

Uji jalur error, bukan hanya happy path

Jalur error sering tidak teruji karena sulit dipicu pada sistem nyata. Mock menghilangkan hambatan tersebut.

Di Apidog, definisikan respons gagal untuk endpoint, lalu beralih di antara mock 422, 429, dan 500. Agen dapat diuji terhadap setiap kondisi tanpa menyentuh produksi. Praktik yang lebih luas dibahas dalam artikel menjalankan agen terhadap mock alih-alih produksi.

Bangun setidaknya lima skenario berikut:

1. Validasi multi-field
   
   Kirim beberapa field salah sekaligus. Pastikan seluruh masalah dikembalikan dalam satu respons dan agen memperbaikinya sekaligus.

2. Rate limit dengan penundaan
   
   Pastikan agen menunggu minimal retry_after_seconds, bukan terus-menerus retry.

3. Server error pada operasi tulis
   
   Pastikan retry tidak membuat resource duplikat.

4. Kegagalan autentikasi
   
   Pastikan agen berhenti, bukan retry. Token buruk tidak akan pulih dengan menunggu. Untuk sisi kredensial, lihat kunci API least privilege untuk agen.

5. Body error salah format
   
   Kembalikan body yang bukan JSON valid. Proxy upstream dapat melakukan ini, sehingga agen harus tetap gagal dengan aman.

Simpan skenario tersebut dan jalankan di CI. Refactor serializer sering merusak bentuk error tanpa terdeteksi oleh test suite happy path.

Dampak praktis dari error yang lebih baik

Respons error yang dapat ditindaklanjuti memberikan tiga hasil nyata:

• Lebih sedikit retry sia-sia
  
  Error {"error":"invalid input"} sering menghasilkan dua atau tiga retry dengan payload yang sama. Error yang menyebut field bermasalah biasanya menghasilkan satu retry yang sudah diperbaiki.

• Lebih sedikit eskalasi ke manusia
  
  Jika error menjelaskan perbaikan, agen dapat menyelesaikan tugas tanpa handoff.

• Debugging lebih cepat
  
  Kombinasi request_id dan detail yang spesifik mengubah pencarian log menjadi satu query.

Manfaat tambahannya: pengembang manusia juga mendapatkan pengalaman debugging yang lebih baik.

Rancang error untuk eskalasi

Sebagian error memang tidak dapat dipulihkan secara otomatis: scope hilang, akun ditutup, atau keputusan bisnis yang membutuhkan persetujuan manusia.

Untuk kasus seperti ini, respons error harus:

• menjelaskan apa yang terjadi;
• menyebut tindakan yang perlu dilakukan manusia;
• membawa ID korelasi;
• tidak menyamarkan kondisi gagal sebagai sukses.

Platform tempat agen berjalan juga perlu menampilkan handoff itu dengan jelas. Misalnya, Sharkly menyimpan hasil agen dan jejak eksekusi pada tugas serta mengarahkan item yang membutuhkan balasan atau review ke Inbox. Namun, handoff hanya berguna jika error Anda lebih informatif daripada "invalid input".

Jangan paksa agen menguraikan prosa

Hindari respons seperti ini:

{
  "message": "Sorry, that didn't work. Please check your details and try again."
}

Agen hanya bisa menebak dari kalimat tersebut. Lebih buruk lagi jika API mengembalikan 200 OK untuk kegagalan bisnis.

Terapkan dua aturan:

1. Berikan kode stabil yang dapat dibaca mesin untuk setiap jenis kegagalan, misalnya insufficient_funds, bukan hanya kalimat “saldo tidak cukup”.
2. Jangan pernah mengembalikan kegagalan dengan status sukses.

200 OK yang berisi error tidak akan terlihat oleh kebijakan retry, dashboard, dan alerting standar.

Checklist error API yang ramah agen

• [ ] Semua error menggunakan satu format terstruktur yang konsisten.
• [ ] detail menyebut field atau kondisi spesifik.
• [ ] Error validasi mengembalikan semua masalah sekaligus beserta path field.
• [ ] Setiap error memiliki boolean retryable.
• [ ] Error yang dapat di-retry menyertakan penundaan dalam detik, pada header dan body.
• [ ] Kegagalan operasi tulis menyatakan apakah data dibuat atau diubah.
• [ ] Setiap error memiliki ID korelasi yang dapat dicari di log.
• [ ] Tidak ada stack trace, string framework, SQL, atau detail internal.
• [ ] Respons error didokumentasikan di OpenAPI dengan deskripsi yang jelas.
• [ ] Mock tersedia untuk setiap error dan skenario dijalankan di CI.

Error adalah antarmuka. Rancang error untuk pemanggil yang benar-benar Anda miliki—yang semakin sering adalah agen atau model yang akan mengikuti instruksi di body respons Anda secara literal.

Unduh Apidog untuk mendefinisikan bentuk error, membuat mock, dan mengujinya sebelum agen menghadapi API Anda di produksi.

Pertanyaan yang sering diajukan

Haruskah menggunakan RFC 9457 atau format error sendiri?

Gunakan RFC 9457 kecuali API Anda sudah memiliki format konsisten di produksi. Konsistensi lebih penting daripada mengganti sebagian endpoint ke format baru. Tambahkan ekstensi seperti retryable dan next_action ke format yang Anda gunakan.

Apakah next_action aman disertakan dalam respons API?

Ya, jika nilainya berasal dari template tetap yang Anda kontrol. Jangan pernah menyalin input pengguna ke next_action, karena agen dapat membacanya sebagai instruksi. Risiko ini dibahas dalam panduan menguji API terhadap input yang tidak tepercaya.

Haruskah error validasi menggunakan 400 atau 422?

Gunakan:

• 400 Bad Request untuk request yang salah format, misalnya JSON rusak.
• 422 Unprocessable Content untuk request yang berhasil diurai tetapi gagal aturan bisnis.

Pemisahan ini membantu agen karena tindakan perbaikannya berbeda. Jika API Anda sudah memakai salah satunya untuk kedua kondisi, dokumentasikan perilakunya dengan jelas daripada mengubah seluruh API tanpa rencana migrasi.

Seberapa banyak detail yang terlalu banyak?

Berhenti saat pemanggil memiliki cukup informasi untuk bertindak. Nama field, aturan validasi, dan nilai contoh biasanya cukup. Identifier internal, query, dan stack frame sudah terlalu jauh.

Apakah pesan error memakan context window?

Ya. Error verbose yang muncul di beberapa retry akan cepat menumpuk. Usahakan body error tetap di bawah beberapa ratus token. Prinsip yang sama dijelaskan dalam panduan memangkas respons API untuk agen.

Bagaimana menghentikan agen dari retry pada error yang tidak dapat dipulihkan?

Atur retryable: false, nyatakan hal tersebut di next_action, dan terapkan aturan yang sama pada tool wrapper. Jangan jadikan penilaian model sebagai satu-satunya mekanisme perlindungan.