Thử lại an toàn
Khi kết nối bị ngắt, bạn không thể biết đơn hàng đã được ghi nhận hay chưa. Vì vậy hãy gửi lại: trong 7 ngày, cùng một khóa idempotency nghĩa là cùng một đơn hàng, và chỉ bị tính phí một lần.
Cách hoạt động
POST /orders cần header Idempotency-Key (khóa idempotency): tối đa 200 ký tự ASCII không có khoảng trắng, do bạn tự tạo và lưu cùng bản ghi đơn hàng của mình. UUID là lựa chọn tốt. Hãy dùng khóa idempotency mới cho đơn hàng mới.
curl -X POST "https://api.talismanleads.io/v1/orders" \
-H "Authorization: Bearer tl_live_your_key_here" \
-H "Idempotency-Key: crm-export-2026-11-05" \
-H "Content-Type: application/json" \
-d '{"checker":"whatsapp_status_detection","entries":["+14155550142","+12125550187"]}'Bạn nhận lại gì
201 và đơn hàng mới.200, cùng đơn hàng, và Idempotent-Replay: true. Không tính thêm phí, ngay cả khi giá đã thay đổi kể từ đó.order_status_unknown hoặc rate_limited.409 idempotency_conflict. Không có đơn hàng nào được đặt.insufficient_balance409 price_changed, và khóa idempotency mới sẽ đặt theo giá mới.Khi bạn không biết
Mọi phản hồi bị mất, order_status_unknown, và phản hồi không phải JSON, ví dụ 502 hoặc 504 của cổng kết nối, đều có cùng một ý nghĩa: hãy lặp lại yêu cầu với cùng khóa idempotency để biết trạng thái thực. Việc này không bao giờ tính phí hai lần. Không bao giờ tạo khóa idempotency mới vì yêu cầu hết thời gian chờ hoặc thất bại: đó là một đơn hàng mới, và sẽ bị tính phí.
Hãy chờ một phút giữa các lần lặp lại. Nếu sau vài phút vẫn nhận phản hồi order_status_unknown, hãy dừng lại và liên hệ bộ phận hỗ trợ kèm request_id. Đừng tạo khóa idempotency mới.
Khóa idempotency tồn tại bao lâu
Khóa idempotency được ghi nhớ trong 7 ngày kể từ lần gửi đầu tiên. Sau đó, cùng khóa này sẽ đặt một đơn hàng mới, vì vậy hãy thử lại trong vòng vài ngày và giữ một khóa idempotency mới cho mỗi đơn hàng mới.