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.

Tvar chyby

Každá chyba je JSON. Jsou dva tvary a liší se tím, odkud chyba pochází.

Odkud	Tvar	Příklad
Od Posty, kvůli obchodnímu pravidlu	Pole `msg` nese lidsky čitelnou větu.	`{ "msg": "No file provided" }`
Z kontroly formátu požadavku	Tvar frameworku: `statusCode`, `message`, `error`.	`{ "statusCode": 400, "message": [...] }`

Schéma ApiError v dokumentu OpenAPI to popisuje i strojově čitelně. U každého stavového kódu uvádí, jestli má smysl to zkusit znovu.

Stavové kódy

Kód	Co to znamená	Typická příčina
400	Požadavek je neplatný.	Chybějící povinné pole, špatný formát data, neznámá hodnota výčtu.
401	Žádný platný přihlašovací údaj.	Chybějící, špatný nebo vyměněný klíč; vypršelý OAuth token.
403	Oprávnění nestačí.	Chybějící scope, nebo vlastníka klíče přeřadili na nižší roli. Odpověď uvede obojí.
404	Takový zdroj neexistuje.	Špatný identifikátor, nebo položka z jiného pracovního prostoru.
402	Tarif to nepovoluje.	Limit je vyčerpaný, nebo funkce k tarifu nepatří.
429	Příliš mnoho požadavků.	Limit volání je vyčerpaný. Viz hlavičku `Retry-After`.
5xx	Něco se u nás pokazilo.	Dočasné. Má smysl to zkusit znovu.

Kdy to zkusit znovu

Stavový kód to řekne

400, 401, 403 a 404 nezmizí, dokud něco nezměníte. Další pokus je jen zátěž. 429 a 5xx jsou dočasné. U nich je správné exponenciálně prodlužovat čekání.

Okamžité publikování je nevratné

Když volání POST /posts skončí vypršením času, nedokážete rozlišit ztracenou odpověď od ztraceného požadavku. Ten nabízející se další pokus publikuje příspěvek dvakrát na něčí skutečný účet. Chraňte volání klíčem idempotence, nebo si nejdřív načtěte kalendář.

Limity volání

Každá odpověď nese tyto hlavičky, s vlastním limitem na každou cestu, na klíč:

Hlavička	Co říká
`RateLimit-Limit`	Jak velký je limit v daném okně.
`RateLimit-Remaining`	Kolik z něj zbývá.
`RateLimit-Reset`	Za kolik sekund se obnoví. Sekundy, ne časové razítko.
`RateLimit-Policy`	Popis platného pravidla.
`Retry-After`	Jen u 429: jak dlouho čekat.

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čekejte na 429. Ze zbývající hodnoty umíte zpomalit předem. Naplánovaná synchronizace, která hlídá zbývající hodnotu, do limitu nikdy nenarazí.

Verze a vyřazování

Verze je v cestě: každé veřejné volání žije pod /public/v1. Nekompatibilní změna by se objevila jako nová verze (/public/v2) a v1 si drží svou smlouvu.

Rozšíření probíhá uvnitř v1: nové volitelné pole, nová cesta, nová hodnota výčtu. Proto váš kód ignoruje pole, která nezná.
Při vyřazování dostane odpověď hlavičku Deprecation: true, v hlavičce Sunset datum, po kterém už nefunguje, a hlavičku Link s podrobnostmi.
Datum Sunset nikdy není blíž než 180 dní od první hlavičky Deprecation.

Momentálně není nic ve vyřazování. Strojový popis je vždy v dokumentu OpenAPI. Pokud se váš kód generuje z něj, rozšíření dostane sám.

Kompletní seznam endpointů najdete na stránce Endpointy.

Něco vám na této stránce chybí? Napište na [email protected] nebo na stránce Nápověda vyplňte formulář.