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 description, 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. nametidak ikut dibandingkan: percobaan ulang yang hanya mengubahnamemengembalikan proses yang sudah ada, dengan nama pertamanya.
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.