Kurallar
Kimlikler, zaman damgaları, hata yapısı, sürümleme ve yeniden denemeler.
| Standart | Kural |
|---|---|
| ID'ler | UUID'ler, opaktır. Onları bütün olarak saklayın; asla ayrıştırmayın veya kısaltmayın. |
| Zaman damgaları | UTC'de RFC 3339, örn. 2026-09-22T04:10:00Z |
| Bilinmeyen alanlar | bunları yoksay. Yeni yanıt alanları ve yeni durum değerleri, sürüm artışı olmadan gelebilir |
| Sürümleme | önek, ana sürümü taşır. Kırıcı bir değişiklik yeni bir önek ve önceden bildirim alır |
| Hatalar | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — şuna göre dallan error.error_code, günlüğe kaydedin açıklama, asla metnine göre eşleştirme. Bkz. Hatalar ve sınırlar |
| Yeniden denemeler | uyun Retry-After 429 durumunda. 5xx durumlarında, üstel geri çekilme ve jitter ile yeniden deneyin |
İdempotentlik
Bir tane gönderin idempotency_key başlattığınız her çalıştırmada bir tane gönderin. Bu sizin kendi dizgenizdir — bir bölüm numarası, bir iş kimliği, o iş birimi için sabit herhangi bir şey.
- Aynı anahtar ile aynı gövde ikinci birini başlatmak yerine zaten var olan çalıştırmayı döndürür.
- Aynı anahtar ile farklı gövde ile reddedilir
idempotency_conflict. Yeni iş için yeni bir anahtar kullanın.
Bu, zaman aşımından sonra yeniden denemeyi güvenli hâle getirir; bu da bir çalıştırma ile ücretlendirileceğiniz bir kopya arasındaki farktır.
İzleme
Her yanıt taşır x-morphic-trace-id. Bunu günlüğe kaydedin. Bir sorun bildirdiğinizde, o kimlik sayesinde çalıştırmayı bir zaman aralığı istemek yerine saniyeler içinde bulabiliriz.