Idempotency-Key Header Added to Scalingo API v2 (2024.02) – Retention Period and Endpoint Coverage Questions

Direct Answers

1. Guaranteed retention period

There is no guaranteed minimum retention. Scalingo's public documentation describes keys as retained for "approximately 24 hours" and notes this may vary by region or change in future updates. That figure reflects the current gateway TTL (in-memory/Redis), not a contractual SLA. Do not build retry logic that assumes keys survive beyond a few hours.

2. Endpoints honoring the header

As of the 2024.02 platform release, the documented v2 endpoints are:

• POST /apps
• POST /addons
• POST /deployments
• POST /domains

The authoritative, up-to-date list is the "Idempotency" section of Scalingo's API reference (developers.scalingo.com, v2 API) together with the platform changelog for release 2024.02. Legacy addon-provisioning flows and endpoints not yet migrated to v2 do not honor the header; the rollout is progressive, so the list grows over time.

3. Behavior after key expiration

The API treats the request as a new write (returns 201 Created or 200 OK). No distinct error code — such as 409 Conflict — signals key expiration. Duplicate resources can therefore be created if retries exceed the retention window.

Confirmed vs. Likely Behavior

Aspect	Documented / Observed	Guaranteed?
Retention window	~24 hours (gateway TTL)	No — best-effort, regional variance
Endpoint list	Four v2 provisioning endpoints (see above)	No — expands progressively; check live reference
Key scope	Per-account, per-endpoint	Likely — reusing a key on a different endpoint or method is not guaranteed to be rejected
Expired-key response	New resource created (201/200)	Reported — no 409 or custom error documented

Treat the retention and scope rows as planning assumptions rather than verified contracts; regional gateway versions may differ by hours, and that variance is not published.

Verification Steps (Run Before Relying on Idempotency)

1. Open the "Idempotency" section of Scalingo's v2 API reference and confirm the current retention wording and endpoint table.
2. Test in your target region: send POST /apps with an Idempotency-Key, wait longer than 24 hours, then retry with the same key and observe whether you get 201 (new app) rather than 409.
3. Check the Scalingo changelog for releases after 2024.02 that mention idempotency expansions.
4. If compliance requires a written retention guarantee, ask Scalingo support for a statement in writing.

A scoped retry pattern that stays inside the window looks like this:

curl -X POST https://api.osc-fr1.scalingo.com/v2/apps \
  -H "Authorization: Bearer $SCALINGO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"app":{"name":"my-app"}}'

Persist that key with the request record and reuse it only for retries of the same logical operation, within the retention window.

One Missing Diagnostic Detail

Which Scalingo region(s) does your application target? Retention variance is not published per region, so multi-region deployments should test idempotency independently in each region before depending on it.