ConverterHQDevelopers
API v1

Idempotency ve retry

Pahalı işlemi veya side effect’i çoğaltmadan güvenle tekrar edin.

Ağ hatası belirsizdir: Client response alamasa da ConverterHQ request’i kabul etmiş olabilir. Create ve handler’lar replay-safe olmalıdır.

Idempotent create

Aynı Idempotency-Key yalnız aynı mantıksal işlem için kullanılmalı; iş ID’niz için client_reference_id ekleyin. Aynı key’i farklı body ile kullanmayın.

Transport retry

Timeout, reset, 429 ve retryable 5xx için exponential backoff+jitter kullanın. Retry-After’a uyun; deterministik 4xx’i otomatik tekrar etmeyin.

Task retry

Execution retry yeni attempt oluşturur ve önceki hatayı korur. Yalnız downstream branch tekrarlanacaksa başarılı upstream Tasks silinmez.

Webhook idempotency

Side effect’ten önce signature doğrulayın, sonra event_id ile dedupe edin. Hızlı yanıt verip yavaş işi kendi queue’nunuza taşıyın.