# Hibák és sebességkorlátok

> A hibaválasz alakja, az API által szándékosan visszaadott összes HTTP-státuszkód, újrapróbálkozási útmutató és útvonalankénti sebességkorlátok.

## Hibaválasz alakja

Az API összes hibája ugyanazt a JSON-borítékot használja:

```json
{ "error": "Magyar hibaüzenet" }
```

Az `error` mező ember által olvasható sztring.

> [!WARNING]
> Az API hibaüzenetei **csak magyarul** érhetők el, függetlenül az `Accept-Language` fejléctől. Ez az általános elérhetőség előtt megváltozik. Példákért lásd a [Konvenciók — Az API-üzenetek nyelve](conventions.md#language) részt.

Ne elemezd az `error` sztringet az újrapróbálkozás vagy az elágazás eldöntéséhez. Helyette a HTTP-státuszkódot használd.

## HTTP-státuszkódok

Az alábbi táblázat tartalmazza az összes HTTP-státuszt, amelyet az API **szándékosan** ad vissza, és hogy a kliensednek mit kell tennie.

| Státusz | Mikor | Teendő |
|---|---|---|
| `200` | Sikeres kérés. | Olvasd a válasz törzsét. |
| `201` | Erőforrás létrehozva (rekordot létrehozó `POST`-végpontok). | Az új erőforrás `id`-ja a válasz törzsében van. |
| `400` | Érvénytelen vagy hibás formátumú kérés: hiányzó kötelező mező, típuseltérés, tartományon kívüli érték vagy érvénytelen JSON. | Javítsd a kérést; ne próbáld újra változtatás nélkül. |
| `401` | Hiányzó hitelesítési adatok, vagy az adatok érvénytelenek. | Ellenőrizd az `Authorization` fejlécet vagy a Basic auth konfigurációt. |
| `403` | Hitelesítve, de nincs jogosultság. Például: az állapotváltoztató kérés megbukott a CSRF-eredet-ellenőrzésen. | Ne próbáld újra a kérés eredetének vagy a hitelesítési kontextus javítása nélkül. |
| `404` | Ismeretlen útvonal vagy nem létező erőforrás-azonosító. | Ellenőrizd az útvonalat és az azonosítót; ne próbáld újra. |
| `405` | A HTTP-metódus nem támogatott ezen az útvonalon. | Használd a megfelelő metódust; ne próbáld újra. |
| `409` | Konfliktus — a művelet a jelenlegi állapotban nem hajtható végre. Például: `POST /api/webhooks/order` készleten kívüli SKU esetén. A hibatest tartalmazza az érintett SKU-t: `"Elfogyott: DEMO-5"`. | Szüntesd meg az ütközési feltételt (pl. ellenőrizd a készletet), majd próbáld újra. |
| `413` | A kéréstest meghaladja a [méretkorlátot](conventions.md#body-limit) (alapértelmezés 1 MB; `POST /api/feeds/import` esetén 10 MB). | Csökkentsd a payload méretét; ne próbáld újra változtatás nélkül. |
| `423` | Az erőforrás le van zárva. | Próbáld újra, miután a zárolás feloldódott. |
| `429` | Túllépted a sebességkorlátot. | Várj legalább 60 másodpercet, majd próbáld újra. Lásd: [Sebességkorlátok](#rate-limits). |
| `500` | Váratlan szerverhiba. | Próbáld újra legfeljebb 3-szor exponenciális visszalépéssel (1 s, 2 s, 4 s). A visszatérő hibákat jelezd a Haszno csapatának. |
| `503` | Felső szintű függőség nem elérhető (például a `POST /api/products/:id/ai-description` által igényelt AI-szolgáltatás). | Próbáld újra visszalépéssel; ez általában átmeneti hiba. |

## Újrapróbálkozási útmutató

### Biztonságosan újrapróbálható

- **`GET`-kérések `5xx` esetén**: próbáld újra legfeljebb 3-szor exponenciális visszalépéssel (1 s → 2 s → 4 s).
- **`429`-válaszok**: várj legalább 60 másodpercet az újrapróbálkozás előtt.

### Nem biztonságos vakon újrapróbálni

Az írási műveletek (`POST`, `PUT`, `PATCH`, `DELETE`) `5xx` esetén esetleg részben sikerültek a szerveren. Mielőtt újrapróbálkoznál:

1. Kérdezd le az aktuális erőforrásállapotot a megfelelő `GET`-tel.
2. A `haszno_proposals_approve` / `POST /api/proposals/approve` által visszaadott `batchId` segítségével görgess vissza egy jóváhagyott köteget, ha szükséges.

> [!TIP]
> `POST /api/products/apply-prices` és `POST /api/proposals/approve` visszaad egy `batchId`-t vagy `applied` számot. Jegyezd fel ezeket az értékeket az újrapróbálkozás előtt, hogy ne alkalmazz árakat kétszer.

### Soha ne próbáld újra

Ne próbáld újra a `400`, `401`, `403`, `404`, `405` vagy `409` válaszokat. A hiba addig megismétlődik, amíg nem javítod a kérést.

## Sebességkorlátok

> [!NOTE]
> A sebességkorlátok példányonként érvényesek a tárolt Vercel-telepítésen. Mivel a szervernélküli függvényhívások különböző hidegindítású példányokon futhatnak, a számlálók nem osztottak a példányok között. A tényleges IP-szintű keret a gyakorlatban magasabb lehet az alább megadott értékeknél. Saját telepítésű rendszeren a számlálók egyetlen folyamaton belül osztottak.

A korlátok kliens-IP-nként érvényesek. Az összes általános írási korlát ablaka **60 másodperc**.

### Általános írási korlátok

Az egyeztetés útvonalprefixum szerint történik; az első egyező szabály érvényes.

| Metódus | Útvonalprefixum | Korlát 60 s alatt |
|---|---|---|
| `POST` | `/api/billing/plan` | 5 |
| `POST` | `/api/shop-connections` | 10 |
| `POST` | `/api/support/conversations` | 20 |
| `PUT` | `/api/support/conversations` | 10 |
| `POST` | `/api/partners/apply` | 10 |
| `POST` | `/api/feeds/import` | 20 |
| `POST`, `PUT`, `PATCH` | Minden más útvonal | 200 |
| `DELETE` | Minden útvonal | 100 |

A `GET`-kérésekre nincs közzétett sebességkorlát. Kerüld a percenkénti egynél sűrűbb lekérdezést; háttér-frissítéshez használj helyi gyorsítótárat.

### Hitelesítési korlátok

Ezek a korlátok elkülönülnek, és eltérő ablakot használnak.

| Végpont | Korlát |
|---|---|
| `POST /api/auth/register` | 5 kérés / IP / óra |
| `POST /api/auth/login` (IP szerint) | 30 kérés / IP / 15 perc |
| `POST /api/auth/login` (e-mail szerint) | 10 kérés / e-mail-cím / 15 perc — **fail-closed**: az ablak lejártáig az adott e-mail-cím további bejelentkezési kísérletei `429`-et kapnak, még helyes jelszóval is |

### Sebességkorlát-válasz

```json
{ "error": "Túl sok kérés — próbáld újra egy perc múlva." }
```

HTTP-státusz: `429`. Az üzenet fordítása: „Túl sok kérés — próbáld újra egy perc múlva."

A [hitelesítési korlátok](#auth-limits) más üzenettel adnak `429`-et: `"Túl sok próbálkozás. Próbáld újra néhány perc múlva."`.