Idempotency

​

Gửi idempotency key

curl -X POST https://api.madiad.com/v1/posts/photos \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Idempotency-Key: 9f1c2e7a-4b6d-4e2a-9c10-7b3f8d5a1e22" \
  -F "profile_id=9f2b4c17-…" \
  -F "platforms[]=instagram" \
  -F "caption=Launch" \
  -F "photos[]=@./launch.jpg"

​

Cách hoạt động

• Request đầu tiên với một key: được xử lý bình thường, kết quả được lưu lại theo key đó.
• Gửi lại cùng key và cùng nội dung: trả về kết quả đã lưu, không tạo thêm bài đăng nào, và response kèm header Idempotent-Replayed: true.
• Cùng key nhưng khác nội dung: bị từ chối với 409 idempotency_conflict. Không có gì được đăng.
• Key khác nhau: được xử lý như một request hoàn toàn mới.
• Bài mà mọi nền tảng đều từ chối (status: "failed"): không có gì được đăng nên key được giải phóng. Hãy sửa nội dung rồi gửi lại, dùng cùng key hoặc key mới.

​

Phân biệt kết quả phát lại với một lần đăng thật

Idempotent-Replayed: true

​

Khi kết quả chưa xác định

{ "error": { "code": "upstream_timeout", "message": "…" }, "status": "unknown", "platforms": ["instagram"], "request_id": "5f29e9927d654c30a4246b56e081bdc1", "job_id": null, "results": null }

1. Tra GET /v1/posts/status bằng request_id đó. Lệnh trả unknown cho tới khi phía nền tảng nhận được bài, sau đó là processing, rồi kết quả (completed, draft, partial hoặc failed). Lịch sử đăng cũng tự cập nhật: khi nền tảng báo kết quả về, chậm nhất là ở lượt kiểm tra hằng ngày kế tiếp.
2. Đừng gửi lại khi bài còn unknown hoặc processing: bài đầu có thể đã lên hoặc đang lên.
3. Nếu kết quả cuối là failed thì không có gì được đăng: lượt đăng được hoàn và Idempotency-Key cũ dùng lại được.
4. Bài chữ hoặc bài video đăng ngay mà chưa tới được nền tảng sẽ được lượt kiểm tra hằng ngày chốt là failed, không sớm hơn. Bài ảnh, bài tài liệu, và mọi bài hẹn giờ hoặc xếp hàng rơi vào trường hợp này thì vẫn là unknown: hãy kiểm tra lịch sử đăng hoặc kiểm tra thẳng trên nền tảng, và nếu bài chưa lên thì gửi lại với một Idempotency-Key mới.
5. Đừng để automation tự retry cùng key rồi mong kết quả khác đi: key cũ vẫn trả đúng câu 502 này, kể cả khi bài đã có kết quả. Kết quả nằm ở lệnh tra trạng thái và ở lịch sử đăng.

​

Khi nào nên dùng

• Một client hoặc công cụ workflow (n8n, queues, cron) tự động thử lại khi timeout.
• Một webhook hoặc job có thể được giao nhiều hơn một lần.
• Người dùng nhấp đúp vào nút đăng bài.