---
title: Idempotency: تکرار امن درخواست | Stard API
url: https://stard-market.ir/docs/idempotency
markdown: https://stard-market.ir/docs/idempotency.md
language: fa
updated: 2026-11-18
description: با هدر Idempotency-Key می‌توانی درخواست ثبت سفارش را بعد از قطعی شبکه بدون خطر خرید دوباره تکرار کنی.
---

# Idempotency: تکرار امن درخواست

> با هدر Idempotency-Key می‌توانی درخواست ثبت سفارش را بعد از قطعی شبکه بدون خطر خرید دوباره تکرار کنی.

## چطور کار می‌کند

برای هر سفارش یک کلید یکتا (مثلاً شماره فاکتور خودت) در هدر `Idempotency-Key` بفرست. اگر همان درخواست با همان کلید دوباره برسد، Stard سفارش تازه نمی‌سازد و پاسخ قبلی را با هدر `Idempotent-Replayed: true` برمی‌گرداند.

```bash
curl -X POST "https://stard-market.ir/api/v1/orders" \
  -H "Authorization: Bearer $STARD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-INV-1042" \
  -d '{"type": "product", "product_id": 4518}'
```

## قواعد

- کلید برای هر کلید API جداست و حداکثر ۶۴ کاراکتر از حروف، عدد و `_-:.`.
- همان کلید با بدنه‌ی متفاوت → `409 idempotency_key_reused`.
- اگر درخواست اول هنوز در جریان باشد → `409 request_in_progress`؛ کمی بعد دوباره بفرست.
- خطای ۵xx ذخیره نمی‌شود، پس تکرار با همان کلید امن است.
