Hibák

A hibák közös borítékot használnak (lásd az áttekintést). Ágazz el a code alapján, naplózd a meta.request_id értéket, és a message mezőt kezeld embereknek szóló angol szövegként.

Kliensoldali hibák

Kód	Állapotkód	Jelentés és teendő
validation_failed	400	Egy mező nem ment át az ellenőrzésen. A field megnevezi; a details elmagyarázza. Javítsd a mezőt.
bad_request	400	A kérés egyáltalán nem olvasható: hibás JSON, sérült Content-Encoding adatfolyam, megszakadt törzs. Nincs javítandó mező; ellenőrizd az átvitelt.
validation_error	400	Az X-Account-Id olyan végpontra érkezett, amely tiltja (/auth/login, /auth/refresh, /auth/swap-company, /auth/logout).
cursor_expired	400	A lapozási kurzor 24 óránál régebbi. Kezdd újra a listázást.
unauthenticated	401	Hiányzó vagy érvénytelen token. Frissítsd a munkamenetet, vagy ellenőrizd a kulcsot.
invalid_signature	401	Egy webhook-aláírás nem ment át az ellenőrzésen. Lásd: Webhookok.
forbidden	403	A token érvényes, de hiányzik a jogosultság.
account_context_mismatch	403	Az X-Account-Id nem egyezik a token fiókjával. A kliens elképzelése az aktuális cégről eltért; olvasd be újra a munkamenetből.
not_found	404	Az erőforrás nem létezik, vagy egy másik fiókhoz vagy webhelyhez tartozik. Az API a kettőt soha nem különbözteti meg.
conflict	409	Állapotütközés: optimista zárolás, egyediségi megkötés, vagy a jelenlegi állapotban nem engedélyezett művelet (például írás egy összevont beszélgetésbe).
idempotency_key_conflict	409	Az Idempotency-Key kulcsot eltérő törzzsel használták újra.
payload_too_large	413	A törzs meghaladja az adott végpontcsalád korlátját.
unsupported_media_type	415	Hibás Content-Type.
unprocessable	422	Érvényes JSON, de egy üzleti szabály elutasította (például munkaidőn kívüli foglalási időpont).
storage_quota_exceeded	422	A fiók elérte a csomagja tárhelykorlátját. A details tartalmazza a used_bytes, quota_bytes és requested_bytes értékeket; szabadíts fel helyet, vagy válts nagyobb csomagra.
rate_limited	429	Lassíts. Tartsd tiszteletben a Retry-After és a details.retry_after_seconds értékét.

Szerveroldali hibák

Kód	Állapotkód	Jelentés és teendő
internal_error	500	Váratlan hiba. Próbáld újra egyszer, majd fordulj az ügyfélszolgálathoz a request_id értékkel.
upstream_unavailable	502	Az átjáró egyáltalán nem érte el a szolgáltatást. Egy rövid újrapróbálkozás általában sikeres.
service_unavailable	503	Tervezett karbantartás vagy nyitott áramkör-megszakító. Próbáld újra a Retry-After fejlécben megadott idő után.
ai_vendor_out_of_funds	503	Az AI-szolgáltatód számlázási okból elutasította a hívást (a szolgáltatótól érkező 402 vagy kvóta miatti 429). Töltsd fel a szolgáltatói fiókot; az újrapróbálkozás nem segít.
upstream_timeout	504	A szolgáltatás nem válaszolt időben. Próbáld újra, ha a retry_after szerepel a válaszban.

Újrapróbálkozás

A 429, 502, 503, 504 hibákat és a hálózati hibákat exponenciális visszalépéssel próbáld újra, és az újrapróbálkozáskor ugyanazt az Idempotency-Key kulcsot küldd, hogy egy írás soha ne hajtódjon végre kétszer. A 429 kivételével a 4xx hibákat ne próbáld újra.