Chyby a limity požiadaviek

Zlyhaná požiadavka vráti stav mimo 2xx a telo JSON so stabilným kódom. Vetvte kód podľa stavu HTTP a podľa code, nikdy podľa textu správy. Anglická verzia: Errors and rate limits.

Formát chybovej odpovede

Každá chyba má rovnaký tvar. code je stabilný strojovo čitateľný reťazec, message je určená ľuďom v jazyku z hlavičky Accept-Language (po slovensky pre sk alebo cs, inak po anglicky) a detail je voliteľný doplnok, napríklad chyby validácie po poliach alebo názov problematického parametra.

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "limit must be between 1 and 100",
    "detail": { "parameter": "limit" }
  }
}

Chybové kódy podľa stavu HTTP

Stav	Kódy	Význam
400	BAD_REQUEST, INVALID_PARAMETER, INVALID_CURSOR, UNSUPPORTED_FILTER	Požiadavka je chybná. Opravte ju pred opakovaním.
401	UNAUTHORIZED	Kľúč chýba, je neplatný, vypršal alebo je zrušený.
402	PAYMENT_REQUIRED	Predplatné organizácie nie je aktívne.
403	FORBIDDEN, LEGACY_KEY_NOT_ALLOWED	Chýba oprávnenie, alebo starší kľúč volá koncový bod len pre v1.
404	NOT_FOUND	Zdroj vo vašej organizácii neexistuje.
409	CONFLICT, IDEMPOTENCY_IN_PROGRESS, LIMIT_EXCEEDED	Konflikt stavu, požiadavka s rovnakým kľúčom ešte beží, alebo ste dosiahli limit tarify.
422	VALIDATION_ERROR, IDEMPOTENCY_KEY_REUSED, TOKEN_OWNER_INACTIVE, WEBHOOK_URL_INVALID, WEBHOOK_URL_BLOCKED, UNKNOWN_EVENT	Požiadavka je v poriadku, ale nedá sa spracovať.
429	RATE_LIMITED	Príliš veľa požiadaviek. Počkajte podľa Retry-After.

Ktoré chyby opakovať

Chybu 429 opakujte po čase z hlavičky Retry-After, odpovede 5xx a sieťové chyby opakujte s exponenciálnym čakaním. Ostatné chyby 4xx neopakujte v nezmenenej podobe, rovnaká požiadavka zlyhá rovnako. Chyba 409 IDEMPOTENCY_IN_PROGRESS sa dá po krátkej pauze bezpečne zopakovať. Pri POST požiadavkách, ktoré opakujete, vždy posielajte Idempotency-Key, pozri Idempotencia.

Pravidlá limitov požiadaviek

Limity sa počítajú za minútu, osobitne pre API kľúč a pre celú organizáciu. Predvolene je to 120 požiadaviek za minútu na kľúč a 600 na organizáciu, pre jednotlivé organizácie sa môžu líšiť, preto skutočné hodnoty čítajte z limits.requests_per_minute a limits.org_requests_per_minute vo volaní GET /me. Limity sa nikdy neviažu na IP adresu, takže viaceré organizácie za jednou výstupnou adresou sa navzájom nebrzdia.

Hlavičky limitov a Retry-After

Každá odpoveď nesie X-RateLimit-Limit (strop najprísnejšieho okna), X-RateLimit-Remaining (zostávajúce požiadavky v okne) a X-RateLimit-Reset (sekundy do obnovenia okna). Odpoveď 429 pridá Retry-After s počtom sekúnd čakania. V dlhšie bežiacej úlohe spomaľte skôr, než sa dostanete na nulu, podľa X-RateLimit-Remaining.

Slučka opakovania v Node.js

Pomocná funkcia rešpektuje Retry-After pri 429, pri 5xx a sieťových chybách čaká exponenciálne a po piatich pokusoch to vzdá. Potrebuje Node.js 18 alebo novší.

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function dakoty(path, init = {}, attempts = 5) {
  const url = `https://api.dakoty.com/api/v1/public${path}`;
  const headers = { Authorization: `Bearer ${process.env.DAKOTY_API_KEY}`, ...init.headers };
  for (let i = 0; i < attempts; i++) {
    let res;
    try {
      res = await fetch(url, { ...init, headers });
    } catch (err) {
      if (i === attempts - 1) throw err;
      await sleep(2 ** i * 500);
      continue;
    }
    if (res.status === 429 || res.status >= 500) {
      if (i === attempts - 1) return res;
      const wait = Number(res.headers.get("retry-after")) * 1000 || 2 ** i * 500;
      await sleep(wait);
      continue;
    }
    return res;
  }
}

Slučka opakovania v Pythone

Rovnaké pravidlá s balíkom requests. Ak do headers dáte Idempotency-Key, pošle sa pri každom pokuse rovnaký, vďaka čomu je opakovanie POST bezpečné.

import os
import time
import requests

BASE = "https://api.dakoty.com/api/v1/public"


def dakoty(method, path, attempts=5, **kwargs):
    headers = {"Authorization": f"Bearer {os.environ['DAKOTY_API_KEY']}", **kwargs.pop("headers", {})}
    for i in range(attempts):
        try:
            r = requests.request(method, BASE + path, headers=headers, timeout=30, **kwargs)
        except requests.RequestException:
            if i == attempts - 1:
                raise
            time.sleep(2**i * 0.5)
            continue
        if (r.status_code == 429 or r.status_code >= 500) and i < attempts - 1:
            time.sleep(float(r.headers.get("Retry-After") or 2**i * 0.5))
            continue
        return r