Idempotency

Mọi endpoint của AstroWay API đều idempotent một cách tự nhiên: cùng một input luôn cho cùng một output, không có tác dụng phụ (ngoại trừ việc trừ credit và ghi log usage).

Điều đó có nghĩa là retry khi gặp lỗi mạng là an toàn. Nhưng để request gửi lại không bị trừ credit hai lần, bạn cần truyền header Idempotency-Key.

Cách sử dụng

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key là một chuỗi tùy ý dài tối đa 64 ký tự, duy nhất cho mỗi thao tác logic. Khuyến nghị dùng ULID hoặc UUID v4.

Cam kết

• Trong vòng 24 giờ kể từ request đầu tiên với key này, các request lặp lại với cùng key sẽ trả về đúng response đó mà không tính toán lại và không trừ credit.
• Nếu body của request khác với bản gốc: trả về 409 Conflict với mã idempotency_key_reuse.
• Sau 24 giờ key bị quên, request mới với cùng key sẽ được xử lý như request bình thường.

Ghi chú

Idempotency là cơ chế chống trừ tiền hai lần khi có sự cố mạng, không phải là cache. Để cache, hãy dùng cơ chế X-Cache có sẵn (5 phút, xem Credit và giới hạn).

Khi nào cần dùng

• Trong webhook handler, khi retry đến từ hệ thống bên ngoài (ví dụ, nhà cung cấp thanh toán hoặc CRM gửi một sự kiện mà bạn parse rồi thực hiện tính toán)
• Trong các background job, nơi retry là hành vi tiêu chuẩn khi gặp lỗi
• Trong pipeline CI/CD, nơi một test có thể chạy lại

Với các tương tác thông thường kiểu “người dùng bấm nút → hiển thị bản đồ sao” thì không cần idempotency: người dùng vẫn sẽ thấy kết quả, và thường không có click lặp lại.

Khi nào không nên dùng

• Đừng đặt key để tiết kiệm credit cho các request giống nhau: việc đó đã có X-Cache (miễn phí, 5 phút)
• Đừng sinh key từ hash(body): khi đó bạn sẽ mất hành vi mặc định của Idempotency-Key (trả 409 khi body khác nhau)