Ribos

Kaip veikia ribos

Ribos apsaugo API ir kitus naudotojus nuo netyčia įsisiautėjusio kliento. Kiekviena politika yra žetonų kibiras. Talpa (angl. burst) nurodo, kiek užklausų galite išsiųsti iš karto. Papildymas nurodo, kiek jų atsinaujina per laiką. Pavyzdžiui, politika read leidžia iš karto išsiųsti 10 skaitymo užklausų, o tada vidutiniškai 5 per sekundę.

Mokėtojas yra komanda, kuri moka už planą, jei naudojate komandos planą. Kitu atveju tai esate jūs. Todėl komandos plane account ir export kibirai bendri visų komandos narių raktams. Daugiau raktų ar daugiau narių papildomos talpos neduoda. Politikos read, write, imports ir me lieka kiekvienam raktui atskiros.

Politika export skaičiuojama prieš skaitant transkriptą, todėl užklausa, kuri baigiasi 404, taip pat sunaudoja vieną jos žetoną.

Viena užklausa gali priklausyti kelioms politikoms. Pavyzdžiui, skaitymas skaičiuojamas ir pagal read, ir pagal account; GET /me – pagal read, account ir me; POST /library/imports – pagal write, imports ir account. Kiekvieno endpointo politikos nurodytos API žinyne.

Papildomai:

• iki 2 lygiagrečių užklausų vienam naudotojui (visiems jo raktams kartu); komandos plane visa komanda dalijasi 3 lygiagrečiomis užklausomis; viršijus grąžinama 429 rate_limit_exceeded su details.policy = concurrency;
• GET /me turi savo ribą (politika me): 5 užklausų pradinė talpa, toliau 1 užklausa per sekundę;
• duomenų bazės užklausoms taikomas bendras apkrovos ribotuvas, todėl apkrovos metu API gali grąžinti 503 service_unavailable su Retry-After: 2. Tai ne jūsų klaida, tiesiog pakartokite.

GET /me atsakymo lauke limits.rate išvardytos raktui taikomos politikos (read, write, imports, account, me ir export) su jų pradine talpa ir papildymu. Skaičiai visiems raktams vienodi, o kieno kibirą jie riboja, nurodyta lentelėje aukščiau. Politika auth_failures ir lygiagretumo riba yra tos, kurios nurodytos lentelėje ir sąraše aukščiau.

Ribų antraštės

Kiekvienas atsakymas į autentifikuotą užklausą, pasiekusią ribotuvą, pateikia ribų būseną dviem būdais. Vienas būdas atitinka IETF RateLimit juodraštį, kitas naudoja plačiai paplitusias X-RateLimit-* antraštes. Atsakymai, atmesti dar prieš taikant ribas, ribų antraščių neturi. Tai trūkstamas ar netinkamas raktas, neleidžiamas IP, nežinomas kelias, netinkamas metodas bei per didelis, netinkamo tipo ar per lėtai gautas užklausos turinys:

RateLimit-Policy: "read";q=10;w=2, "account";q=20;w=2
RateLimit: "read";r=7;t=1
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1

Gavus 429

Viršijus ribą API grąžina 429 rate_limit_exceeded su antrašte Retry-After (sveikos sekundės, ne mažiau kaip 1, iki kito žetono). error.details.policy nurodo, kuri politika viršyta (pavyzdys su Accept-Language: lt):

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Per daug užklausų. Sulėtinkite ir bandykite po Retry-After nurodyto laiko.",
    "doc_url": "https://diko.app/api-docs/klaidos#rate_limit_exceeded",
    "details": { "policy": "read", "retry_after": 1 }
  },
  "request_id": "req_QBPIQ5QTIWAUYTMDNCLD7CMKBE"
}

Ką daryti:

1. Palaukite Retry-After sekundžių ir pridėkite nedidelę atsitiktinę paklaidą, kad keli klientai nesikartotų vienu metu.
2. Vienu metu vykdykite ne daugiau kaip 2 užklausas visai paskyrai: riba skaičiuojama visiems jūsų raktams kartu, o komandos plane – ir visų narių raktams.
3. Sąrašus skaitykite dideliais puslapiais (limit=100) ir sekite has_more, o ne kvieskite po vieną elementą.
4. Vietoj nuolatinio tikrinimo naudokite webhooks arba GET /events.

Pakartojimo pagalbinį kodą rasite puslapyje Klaidos.

Importų talpa

Importai turi papildomą apsaugą, nes jie naudoja kreditus ir apdorojimo eilę. Kiekvienas sprendimas priimamas kuriant importą:

Paros riba skaičiuoja visus per pastarąsias 24 valandas sukurtus importus, įskaitant tuos, į kuriuos atsakyta iš jūsų bibliotekos ar bendros Diko talpyklos (reused: true). Jie kreditų nekainuoja, bet vis tiek yra importai.

Viršijus bet kurią ribą API grąžina 429 queue_limit_exceeded su Retry-After: 60. error.details.limit nurodo, kuri riba pasiekta: user_active_imports, capacity (visiems naudotojams) arba user_daily_imports. Palaukite, kol dalis importų baigsis, o ne siųskite daugiau užklausų.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "code": "queue_limit_exceeded",
    "message": "Per daug importų eilėje ar vykdomų. Bandykite vėliau.",
    "doc_url": "https://diko.app/api-docs/klaidos#queue_limit_exceeded",
    "details": { "limit": "user_active_imports", "retry_after": 60 }
  },
  "request_id": "req_QBPIQ5QTIWAUYTMDNCLD7CMKBE"
}

Autentifikacijos klaidų riba

Politika auth_failures riboja bandymus su blogais raktais iš to paties patikimo IP. Nematytų raktų tikrinimui taikomas ir bendras biudžetas. Todėl bandymai spėlioti raktus gauna invalid_api_key be papildomos informacijos. Pakartotinai siųsti tą patį blogą raktą beprasmiška.