Weekly Sume run idempotency key from the ISO week: 2026 has 53

What should the idempotency key for a weekly run look like?

Derive it from the thing being made, not from a random id. For a weekly run that is the week. A Format run accepts an Idempotency-Key header of up to 255 characters: the first request answers 202, a replay with the same body answers 200 with the original receipt, and the same key with a different body is a 409.

If your scheduler fires twice or retries after a timeout, both calls carry the same key and only one run exists. That is the whole point, and it only works if the key is stable across the retry.

Which week number should I use?

Use the ISO 8601 week, with the ISO year. Python's strftime exposes both as %G and %V. The common mistake is mixing the calendar year %Y with the ISO week %V.

2026 is a 53-week ISO year. December 28, 2026 through January 3, 2027 all belong to week 53 of 2026. January 1, 2027 is therefore 2026-W53 by ISO rules, and January 4, 2027 starts 2027-W01. In the other direction, December 29, 2025 is 2026-W01. A key built from %Y and %V would call January 1, 2027 2027-W53, a week that does not exist.

from datetime import date

def week_key(day: date, name: str = "promo") -> str:
    return f"{name}-{day.strftime('%G-W%V')}"

for d in (date(2025, 12, 29), date(2026, 12, 31),
          date(2027, 1, 1), date(2027, 1, 4)):
    print(d, week_key(d))

What does that print, and how do I use it?

The loop prints promo-2026-W01, promo-2026-W53, promo-2026-W53 and promo-2027-W01. Send the result as the Idempotency-Key on the weekly run.

If you deliberately want to re-run a week, bump a suffix such as -r2; the body should change only when you mean it to.

• Compute the key from the scheduled time, not from the time the job happens to execute.
• Treat 200 and 202 as success and store data.id either way.
• Never reuse a weekly key with a changed body, or you will get a 409.
• Sume's own scheduled runs, created in the app, have their own skip-on-active behavior; this key is for schedules you run yourself.