Idempotency
Idempotency-Key başlığıyla ödeme ve End Customer oluşturmayı güvenle yeniden deneyin.
Neden önemli
Bir istek, biz işlemi yaptıktan sonra zaman aşımına uğrayabilir. Koruma olmadan isteği yeniden göndermek ikinci bir ödeme oluşturabilir. Idempotency-Key ile yeniden deneme ilk yanıtı geri alır ve hiçbir işlem iki kez yapılmaz.
Hangi istekler anahtar alır
| İstek | Idempotency-Key |
|---|---|
POST /v1/payouts | Zorunlu |
POST /v1/end-customers | Zorunlu |
Bu istekler başlık olmadan idempotency_key_required (400) ile reddedilir. Diğer istekler başlığı yok sayar.
Bir anahtar seçin
- 1 ile 128 karakter arasında herhangi bir metin. UUID v4 iyi bir seçimdir. Daha uzun bir anahtar
idempotency_key_invalid(400) ile reddedilir. - Her işlem için bir anahtar: ödemeyi yapmaya karar verdiğiniz anda üretin, kendi ödeme kaydınızla birlikte saklayın ve o ödemenin her yeniden denemesinde aynısını kullanın.
- Bir anahtarı asla başka bir işlem için yeniden kullanmayın.
curl -X POST "$APEX_BASE_URL/v1/payouts" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f6c1d2e-8a4b-4c9d-b1e7-5a2f9c8d0e13" \
-d '{"quote_id":"qt1.eyJkIjoiNmUyYTljNGYtOGIxZC00ZjM3..."}'Yeniden denemede ne olur
Bir anahtar; API anahtarı başına, (Apex-End-Customer gönderiyorsanız) adına işlem yaptığınız End Customer başına, yöntem ve yol başına tutulur. Bu kapsam içinde:
| Durum | Yanıt |
|---|---|
| İlk istek | Normal şekilde çalışır. Başarılı yanıt 24 saat saklanır. |
| Başarıdan sonra aynı anahtar, aynı gövde | Saklanan yanıt; aynı durum kodu ve gövdeyle, Idempotency-Replayed: true başlığıyla. Hiçbir şey yeniden çalışmaz. |
| Aynı anahtar, farklı gövde | idempotency_key_reused (422). |
| İlk istek hâlâ sürerken aynı anahtar | idempotency_in_progress (409). Biraz sonra yeniden deneyin; hiç bitmeyen bir istek anahtarı en geç bir dakika içinde serbest bırakır. |
| İlk istek bir hatayla bittikten sonra aynı anahtar | Yeniden çalışır. Hatalar saklanmaz; o arada düzelttiğiniz bir nedenle reddedilen istek aynı anahtarla geçebilir. |
| 24 saatten sonra | Yeni bir istek olarak çalışır. |
Aynı baytları gönderin
"Aynı gövde", bayt bayt aynı demektir. İlk seferde gönderdiğiniz serileştirilmiş gövdeyi saklayıp aynen yeniden gönderin. Bir nesneyi yeniden serileştirmek anahtarların sırasını ya da boşlukları değiştirebilir ve istek idempotency_key_reused ile reddedilir.
Kapsam API anahtarını içerdiğinden, farklı bir API anahtarıyla gönderilen yeniden deneme yeni bir istektir. Ödemelerde ikinci bir koruma daha vardır: bir teklif yalnızca bir ödemeye dönüşür ve onu yeniden kabul etmek quote_already_used (409) döner. Bu kodu alırsanız oluşturulan ödemeyi bulmak için son ödemelerinizi GET /v1/payouts ile okuyun.
Bir yeniden deneme yardımcısı
Aşağıdaki yardımcılar ağ hatalarında, 429 ve 5xx yanıtlarında aynı anahtar ve aynı gövde baytlarıyla yeniden dener.
import { randomUUID } from "node:crypto";
export async function createPayout(quoteId, idempotencyKey = randomUUID()) {
const body = JSON.stringify({ quote_id: quoteId }); // serialise once
for (let attempt = 0; attempt < 5; attempt++) {
let res;
try {
res = await fetch(`${process.env.APEX_BASE_URL}/v1/payouts`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.APEX_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body,
});
} catch {
await sleep(backoff(attempt));
continue; // network error: the payout may exist, so retry with the same key
}
if (res.ok) return res.json();
const err = await res.json().catch(() => ({}));
if (res.status === 429) {
await sleep(Number(res.headers.get("Retry-After") ?? "1") * 1000);
} else if (res.status >= 500 || err.code === "idempotency_in_progress") {
await sleep(backoff(attempt));
} else {
throw Object.assign(new Error(err.message), err);
}
}
throw new Error(`payout not confirmed; retry later with key ${idempotencyKey}`);
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const backoff = (n) => Math.min(1000 * 2 ** n, 16000) + Math.random() * 250;Yardımcı vazgeçtiğinde ödeme oluşmuş da olabilir, oluşmamış da. Anahtarı saklayın: 24 saat içinde aynı anahtar ve gövdeyle yapılan sonraki bir deneme, ödeme oluştuysa onu döner; oluşmadıysa ve teklif hâlâ geçerliyse oluşturur.