Nyilvános API

Hibák, hívási korlátok, verziózás

A hibaválaszok alakja, mikor érdemes újrapróbálni, a RateLimit fejlécek, és hogyan vezetünk ki egy útvonalat.

A hiba alakja

Minden hiba JSON. Kétféle alak van, és a különbség az, honnan jön a hiba.

Honnan	Alak	Példa
A Postytól, üzleti szabály miatt	A `msg` mező hordozza az emberi mondatot.	`{ "msg": "No file provided" }`
A kérés formai ellenőrzésétől	A keretrendszer alakja: `statusCode`, `message`, `error`.	`{ "statusCode": 400, "message": [...] }`

Az OpenAPI dokumentum ApiError sémája mindezt géppel olvashatóan is leírja, státuszkódonként azzal együtt, hogy érdemes-e újrapróbálni.

Státuszkódok

Kód	Mit jelent	Tipikus ok
400	A kérés hibás.	Hiányzó kötelező mező, rossz dátumformátum, ismeretlen felsorolt érték.
401	Nincs érvényes hitelesítő adat.	Hiányzó, hibás vagy lecserélt kulcs; lejárt OAuth-token.
403	Nincs elég jogosultság.	Hiányzó scope, vagy a kulcs tulajdonosát lefokozták. A válasz megnevezi mindkettőt.
404	Nincs ilyen erőforrás.	Rossz azonosító, vagy másik munkaterülethez tartozó elem.
402	A csomag nem engedi.	Keret betelt, vagy a funkció nem tartozik a csomaghoz.
429	Túl sok kérés.	A hívási keret betelt. Lásd a `Retry-After` fejlécet.
5xx	Nálunk hibázott valami.	Átmeneti. Érdemes újrapróbálni.

Mikor próbáld újra

A státuszkód megmondja

A 400, 401, 403 és 404 addig nem múlik el, amíg nem változtatsz valamin: az újrapróbálkozás csak terhelés. A 429 és az 5xx átmeneti, ezeknél az exponenciálisan növekvő várakozás a helyes viselkedés.

Az azonnali közzététel visszafordíthatatlan

Ha egy POST /posts hívás időtúllépéssel zárul, nem tudod megkülönböztetni az elveszett választ az elveszett kéréstől. A kézenfekvő újrapróbálkozás kétszer tesz ki egy bejegyzést valakinek a valódi fiókjára. Idempotenciakulccsal védd a hívást, vagy előbb kérdezd le a naptárat.

Hívási korlátok

Minden válasz viszi ezeket a fejléceket, útvonalanként külön kerettel, kulcsonként:

Fejléc	Mit mond
`RateLimit-Limit`	Mekkora a keret az adott ablakban.
`RateLimit-Remaining`	Mennyi maradt belőle.
`RateLimit-Reset`	Hány másodperc múlva áll vissza. Másodperc, nem időbélyeg.
`RateLimit-Policy`	Az érvényes szabály leírása.
`Retry-After`	Csak 429 mellett: mennyit várj.

curl -i https://api.posty.hu/public/v1/integrations \
  -H "Authorization: psty_a_kulcsod"

RateLimit-Limit: 60
RateLimit-Remaining: 58
RateLimit-Reset: 41
RateLimit-Policy: 60;w=60

Ne a 429-re várj: a maradék értékből előre tudsz lassítani. Egy ütemezett szinkron, ami a maradékot figyeli, soha nem fut bele a korlátba.

Verziózás és kivezetés

A verzió az útvonalban van: minden nyilvános hívás a /public/v1 alatt él. Törő változás új verzióként jelenne meg (/public/v2), a v1 pedig tartja a szerződését.

Bővítés a v1-en belül történik: új opcionális mező, új útvonal, új felsorolt érték. Ezért a kódod hagyja figyelmen kívül azokat a mezőket, amiket nem ismer.
Kivezetéskor a válasz Deprecation: true fejlécet kap, mellé Sunset fejlécben a dátumot, ami után már nem működik, és egy Link fejlécet a részletekkel.
A Sunset dátum soha nem lehet közelebb 180 napnál az első Deprecation fejléctől számítva.

Jelenleg semmi nincs kivezetés alatt. A gépi leírás mindig az OpenAPI dokumentumban van; ha a kódod abból generálódik, a bővítéseket magától megkapja.

A végpontok teljes listáját a Végpontok oldalon találod.

Hiányzik valami erről az oldalról? Írj a [email protected] címre, vagy használd a Segítség oldal űrlapját.