Menangani kesalahan di alur kerja NextPDF Connect

Sekilas pandang

Bangun alur kerja Connect yang tangguh. Validasikan setiap hasil tool, tutup sesi yang gagal, lalu coba lagi dari keadaan baru. Tool yang gagal mengembalikan hasil kesalahan yang terstruktur. Perlakukan hasil tersebut sebagai respons normal, bukan sebagai kegagalan transport. PHP Standards Recommendation (PSR)-18 membuat pembedaan yang sama: respons tetap dikembalikan meskipun statusnya menunjukkan kesalahan (PSR-18 §3).

Pemasangan

composer require nextpdf/server

Ikatkan sebuah transport. Resep ini menggunakan create_pdf, add_text, dan output_pdf. Ketiga tool tersebut adalah Core.

Tinjauan konseptual

Pemanggilan tool yang gagal mengembalikan hasil kesalahan. Hasil tersebut memuat flag kesalahan, pesan yang dapat dibaca manusia, dan kode jika tersedia. Hasil yang berhasil tidak memiliki flag kesalahan dan memuat keluaran normal dari tool tersebut. Dalam kedua kasus, transport telah mengirim permintaan dan menerima respons (PSR-18 §p2).

Jaga agar loop defensif tetap singkat. Kirim panggilan, lalu baca hasilnya. Jika hasilnya adalah kesalahan, catat dalam log, klasifikasikan, terapkan strategi pemulihan, dan berhenti menggunakan keadaan yang sudah usang. Jika tidak, ekstrak field yang Anda butuhkan, lalu lanjutkan.

Permukaan API

Tool	Peran	Tingkat risiko
`create_pdf`	Membuka sesi	Aman
`add_text`	Menulis teks	Hati-hati
`output_pdf`	Merender dan mengembalikan PDF	Persetujuan Diperlukan / Tinjauan (base64)

Katalog tool adalah sumber kebenaran. Tool yang tersedia bergantung pada tier yang terpasang.

Contoh kode — Mulai cepat

Jalankan happy path (create_pdf → add_text → output_pdf) dan periksa setiap hasilnya. Kemudian, dengan sengaja gunakan kembali document_id yang sudah dihancurkan pada add_text untuk memicu kesalahan sesi. Pulihkan dengan membuat sesi baru dan memutar ulang kontennya.

Contoh kode — Produksi

Klasifikasikan kesalahan berdasarkan kategori, lalu tanggapi sesuai kategorinya:

Validasi input — deterministik. Perbaiki argumennya, lalu coba lagi panggilan yang sama. Contoh: teks kosong, perataan tidak valid, ukuran non-positif, ukuran halaman tidak dikenal, keluarga huruf tidak dikenal.
Sesi — document_id sudah tidak ada lagi. Buat sesi baru, lalu putar ulang semua konten.
Sistem — keterbatasan sumber daya server, seperti batas sesi. Tunggu sejenak, lalu coba lagi.
Persetujuan — output_pdf ke sebuah berkas dapat berhenti sejenak untuk menunggu persetujuan manusia. Ini adalah jeda alur kerja, bukan kegagalan. Teruskan tantangan tersebut dan tunggu, lalu panggil ulang dengan token konfirmasi.

Jangan pernah berasumsi bahwa pemanggilan berhasil. Jangan pernah menggunakan kembali document_id setelah terjadi kesalahan sesi. Jangan pernah mengirim output_pdf sebelum setiap langkah konten berhasil.

Kasus tepi & jebakan

Persetujuan bukanlah kesalahan. Tantangan human-in-the-loop (HITL) adalah jeda. Jangan mencoba lagi dalam loop yang rapat. Teruskan tantangan tersebut kepada manusia.
Server dimulai ulang. Semua sesi dalam memori terhapus, dan setiap document_id sebelumnya menjadi tidak valid.
Alur kerja sebagian. Jika add_text gagal di tengah dokumen, sesi bisa menjadi tidak konsisten. Pemulihan yang aman adalah sesi yang baru, bukan perbaikan sebagian.

Kinerja

Dapat diabaikan. Resep ini membahas alur kendali, bukan proses rendering. Profilnya adalah structural untuk setiap keluaran yang dihasilkan.

Catatan keamanan

Pesan kesalahan ditujukan untuk agen pemanggil dan operator. Jangan menampilkan teks kesalahan mentah dari server secara verbatim kepada pengguna akhir yang tidak tepercaya. Tampilkan pesan yang sudah diklasifikasikan dan dibersihkan sebagai gantinya.

Kesesuaian

Pernyataan	Spesifikasi	Klausa	reference_id
Transport mengembalikan respons apa pun hasilnya.	PSR-18	§p2
Respons tetap dikembalikan meskipun statusnya kesalahan.	PSR-18	§3

Konteks komersial

Tidak berlaku — semua tool adalah Core.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya	Kesalahan datang sebagai hasil tool dengan flag kesalahan.
REST	Ya	Status non-2xx membawa body kesalahan terklasifikasi yang sama.
gRPC	Ya	Kode status ditambah pesan hasil kesalahan.

Pada setiap transport, periksa kesalahan tingkat tool sebagai respons normal, bukan sebagai panggilan yang gagal terkirim (PSR-18 §3).

Tingkat risiko HITL

create_pdf bersifat Safe, add_text bersifat Caution, dan output_pdf bersifat Approval Required, diturunkan menjadi Review dalam mode base64. Penulisan berkas yang tertunda muncul sebagai tantangan persetujuan. Loop kesalahan harus memperlakukannya sebagai jeda, bukan kegagalan (tingkat risiko HITL).

Envelope JSON gerbang konfirmasi

Persetujuan yang tertunda mengembalikan:

{ "allowed": false, "challenge": "<human-readable challenge text>", "token": "confirm_<single-use-hex>" }

Panggil ulang tool yang sama dengan _confirmation_token diatur ke token tersebut. Tool tersebut mengembalikan { "allowed": true }. Untuk alur lengkapnya, lihat output-approval.