Gränser & retry

API:t öppnar fysiska dörrar. Retry-policyn är därför inte en optimering utan en säkerhetsfråga.

Är unlock säkert att försöka om?#

• Vid fel: visa resultatet för en människa och låt personen trycka igen. Det är den enda säkra "retryn".
• Logga varje försök i er egen audit-logg med tidsstämpel, aktör och {deviceId}.
• Hur länge dörren står olåst efter en upplåsning är konfigurerat per enhet. Behöver ni veta det exakta värdet för era enheter, fråga KiiOn.

Retry-policy per operation#

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function withBackoff<T>(fn: () => Promise<Response>, attempts = 4): Promise<Response> {
  for (let attempt = 0; ; attempt++) {
    const res = await fn();
    if (!RETRYABLE.has(res.status) || attempt >= attempts - 1) return res;

    const retryAfter = Number(res.headers.get("Retry-After")) * 1000;
    const backoffMs = Number.isFinite(retryAfter) && retryAfter > 0
      ? retryAfter
      : 2 ** attempt * 500 + Math.random() * 250; // jitter: never a synchronised thundering herd
    await sleep(backoffMs);
  }
}
// NOTE: never wrap PUT /device/{deviceId}/unlock in this. See "Is unlock safe to retry?".

Hur ofta ni bör anropa#

Kvoter och throttling#

KiiOn publicerar i dagsläget inga numeriska anropstak per konto. Bygg därför klienten så att den hanterar throttling korrekt oavsett: respektera 429 och Retry-After, backa av exponentiellt och låt aldrig en retry-loop springa fritt. Behöver ni ett garanterat tak för ett högvolymsfall — hör av er till developers@kiion.io innan driftsättning.