Haszno.comDokumentáció
HUENDemó megnyitása ↗
API-referencia
Megnyitás Markdownként

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:

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

Az error mező ember által olvasható sztring.

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 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 (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.
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.

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

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

{ "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 más üzenettel adnak 429-et: "Túl sok próbálkozás. Próbáld újra néhány perc múlva.".