---
title: "Hibák, hívási korlátok, verziózás | Posty dokumentáció"
description: "A hibaválaszok alakja, mikor érdemes újrapróbálni, a RateLimit fejlécek, és hogyan vezetünk ki egy útvonalat."
canonical: https://posty.hu/dokumentacio/api/hibak
source: https://posty.hu/dokumentacio/api/hibak.md
---

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
```

Kód másolása

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](https://posty.hu/openapi.json) 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](https://posty.hu/dokumentacio/api/vegpontok) oldalon találod.

Dokumentációs oldalak

Hiányzik valami erről az oldalról? Írj a [norbert@posty.hu](mailto:norbert@posty.hu) címre, vagy használd a [Segítség](https://posty.hu/segitseg) oldal űrlapját.