Konvensi
Id, timestamp, bentuk error, versioning, dan percobaan ulang.
| Konvensi | Aturan |
|---|---|
| ID | UUID, bersifat opak. Simpan utuh; jangan pernah mem-parse atau mempersingkatnya |
| Stempel waktu | RFC 3339 dalam UTC, misalnya 2026-09-22T04:10:00Z |
| Field tidak dikenal | abaikan. Field respons baru dan nilai status baru dapat muncul tanpa perubahan versi |
| Versioning | prefiks membawa versi mayor. Perubahan yang memutus kompatibilitas mendapat prefiks baru dan pemberitahuan sebelumnya |
| Kesalahan | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — cabangkan pada error.error_code, catat deskripsi, jangan pernah cocokkan berdasarkan teksnya. Lihat Kesalahan & batas |
| Coba lagi | patuhi Retry-After pada 429. Pada 5xx, coba lagi dengan exponential backoff dan jitter |
Idempoten
Kirim sebuah idempotency_key pada setiap proses yang Anda mulai. Itu adalah string Anda sendiri — nomor episode, ID pekerjaan, apa pun yang stabil untuk unit kerja itu.
- Kunci yang sama dengan isi yang sama mengembalikan proses yang sudah ada, alih-alih memulai yang kedua.
- Kunci yang sama dengan sebuah isi yang berbeda ditolak dengan
idempotency_conflict. Gunakan kunci baru untuk pekerjaan baru.
Itu membuat percobaan ulang setelah timeout aman, yang merupakan perbedaan antara satu proses dan duplikat yang akan ditagihkan kepada Anda.
Pelacakan
Setiap respons membawa x-morphic-trace-id. Catat. Saat Anda melaporkan masalah, ID itulah yang memungkinkan kami menemukan proses tersebut dalam hitungan detik, alih-alih meminta Anda memberi rentang waktu.