Chuyển tới nội dung
Sursa Developers

Yêu cầu lặp lại an toàn

Một yêu cầu có thể thất bại sau khi Sursa đã thực hiện xong công việc: kết nối bị ngắt, hoặc tiến trình của bạn khởi động lại trước khi phản hồi tới. Nếu bạn gửi lại cùng yêu cầu POST, bạn có thể tạo ra thẻ thứ hai hoặc webhook thứ hai. Khóa idempotency ngăn điều đó.

Hãy gửi header Idempotency-Key với mỗi yêu cầu POST và PATCH. Nếu Sursa đã thấy một yêu cầu với khóa này, Sursa không thực hiện lại thao tác: nó trả về phản hồi đã lưu ở lần đầu.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Yêu cầu lặp lại nhận cùng trạng thái và phần thân như yêu cầu đầu tiên, kèm một header bổ sung:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

Yêu cầu lặp lại có X-Request-Id riêng.

Chọn khóa

  • Dùng một giá trị ngẫu nhiên mới, chẳng hạn UUID v4, cho mỗi thao tác logic: “tạo thẻ này”, “đăng ký webhook này”. Dùng cùng giá trị cho mọi lần thử lại của thao tác đó, và không bao giờ dùng cho thao tác khác.
  • Một khóa tốt được suy ra từ dữ liệu của chính bạn khi có, ví dụ sync-2026-10-24-record-1042. Khi đó ngay cả tác vụ đã khởi động lại và mất trạng thái trong bộ nhớ cũng gửi lại đúng khóa đó.
  • Khóa gồm từ 1 đến 255 ký tự ASCII in được. Mọi giá trị khác trả về 400 với mã api.idempotency_key_invalid.

Sursa làm gì với khóa

Tình huốngPhản hồi
Yêu cầu đầu tiên với khóa nàyThao tác được thực hiện như bình thường.
Cùng khóa, cùng yêu cầu, yêu cầu đầu tiên kết thúc với 2xx hoặc 4xxPhản hồi đã lưu, với Idempotency-Replayed: true. Thao tác không được thực hiện lại.
Cùng khóa, yêu cầu đầu tiên vẫn đang chạy409 api.idempotency_in_progress với Retry-After: 1. Hãy chờ rồi thử lại.
Cùng khóa, khác phương thức, đường dẫn, Content-Type hoặc phần thân409 api.idempotency_mismatch. Khóa đã được một yêu cầu khác sử dụng.
Yêu cầu đầu tiên kết thúc với 5xx hoặc 429Khóa được giải phóng: yêu cầu tiếp theo với khóa này thực hiện lại thao tác.
  • Khóa có hiệu lực trong 24 giờ. Sau đó, cùng khóa sẽ bắt đầu một thao tác mới.
  • Khóa được tách riêng theo tổ chức và theo bên gọi: hai khóa API khác nhau có thể dùng cùng một giá trị mà không ảnh hưởng tới nhau.
  • Phản hồi lỗi 4xx cũng được lưu. Yêu cầu có dữ liệu không hợp lệ sẽ thất bại theo cùng cách khi được lặp lại với cùng khóa; hãy sửa nó và gửi với khóa mới.

Yêu cầu nào cần khóa

Phương thứcIdempotency-Key
POST, PATCHHãy gửi. Mọi endpoint lưu phản hồi của mình cho lần lặp lại đều liệt kê header này trong tài liệu tham chiếu API.
GET, PUT, DELETEKhông cần: theo bản chất, các phương thức này lặp lại an toàn. Header được chấp nhận nhưng không có tác dụng.
POST chỉ đọc, chẳng hạn tìm kiếm, các báo cáo tài chính và POST /v1/catalog/resolveĐược chấp nhận, nhưng không có gì được lưu: yêu cầu chỉ đơn giản chạy lại.

Một số thao tác lặp lại an toàn ngay cả khi không có header:

  • PUT /v1/cards-by-external-id/{external_id} tạo hoặc thay thế thẻ có ID của bạn; lặp lại với cùng nội dung không thay đổi gì.
  • Tài liệu của nguồn tùy chỉnh được định danh bằng external_id của bạn; gửi lại cùng tài liệu trả về unchanged.
  • Câu trả lời dạng luồng của POST /v1/chat dùng trường request_id trong phần thân thay cho header. Xem Xây dựng bot hỏi đáp.

Thử lại an toàn

Kết hợp khóa với các quy tắc thử lại trong Lỗi: tạo khóa một lần, trước lần thử đầu tiên, và gửi nó với mọi lần thử của cùng một thao tác.