Hibakódok

Az API minden hibája egységes borítékot ad:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Érvénytelen vagy hiányzó API kulcs.",
    "status": 401,
    "requestId": "req_a1b2c3d4e5f6a7b8"
  }
}

A kódodban mindig a code mezőre ágazz el, ne az üzenet szövegére (az üzenet emberi olvasásra való, és változhat). A requestId-t add meg, ha hibát jelentesz nekünk. A boríték általános leírását az API referencia tartalmazza.

Az alábbi táblázatok a REST végpontok által ténylegesen visszaadott kódokat sorolják, HTTP státusz szerint. A rendszerben létező, de a REST hívásokból közvetlenül nem visszatérő kódokat az Egyéb kódok szakasz gyűjti.

400 — A kérés hibás

Kód	Jelentés	Gyakori ok	Teendő
INVALID_REQUEST_BODY	a kéréstörzs érvénytelen	hibás vagy hiányzó mező, rossz típus	Javítsd a kérést a details.issues lista alapján. Ne küldd újra változatlanul.
MISSING_REQUIRED_FIELD	kötelező mező hiányzik	pl. GET /v1/customers paraméter nélkül, vagy external_system kulcsnál hiányzó externalId	Add meg a hiányzó mezőt (lásd details).
INVALID_CURSOR	érvénytelen lapozási kurzor	sérült starting_after, vagy a szűrők változtak lapozás közben	Kezdd újra az első oldaltól, és lapozás közben ne változtasd a szűrőket.
EXTERNAL_SYSTEM_NOT_CONFIGURED	a kulcson nincs külső rendszer beállítva	külső azonosítóval dolgozó hívás külső rendszer nélküli kulccsal	Használj olyan kulcsot, amelyhez tartozik külső rendszer azonosító.
EXTERNAL_SYSTEM_AMBIGUOUS	a cél névtér nem egyértelmű	külső azonosító írása több névteres kulccsal, elsődleges névtér és explicit externalSystem nélkül	Add meg az externalSystem mezőt, vagy állíts be elsődleges névteret a kulcson.
EXTERNAL_ID_FIELD_MISMATCH	ellentmondó külső azonosító	ügyfél létrehozásakor az externalId és a hozzá tartozó egyedi mező (customFields) eltérő értéket küld	Küldd ugyanazt az értéket mindkét helyen, vagy hagyd ki a customFields-ből (az externalId elég).
EXTERNAL_ID_NOT_SINGLE_TOKEN	az externalId elválasztó karaktert tartalmaz	„több azonosító egy mezőben“ módú névtérnél az externalId értékében elválasztó szerepel (/, ,, ;), akár létrehozáskor, akár célzott (externalSystem megadott) keresésnél	Egyetlen azonosítót adj meg. A teljes felsorolás a hozzá tartozó egyedi mezőbe (customFields) való, keresni pedig az egyes azonosítókra lehet.

Ezek a hibák a kérés javításával oldhatók meg, újrapróbálás önmagában nem segít.

401 — Hitelesítés sikertelen

Kód	Jelentés	Gyakori ok	Teendő
INVALID_API_KEY	érvénytelen vagy hiányzó kulcs	hiányzó vagy rossz Authorization fejléc, ismeretlen vagy visszavont kulcs	Ellenőrizd a kulcsot és a fejlécet. A REST híváson a visszavont kulcs is ezt a hibát adja.

403 — Nincs jogosultság

Kód	Jelentés	Gyakori ok	Teendő
MISSING_PERMISSION	a kulcsnak nincs joga a művelethez	hiányzó jogosultság (lásd details.required)	Adj a kulcsnak megfelelő jogosultságot a beállításokban.
KEY_EXPIRED	a kulcs lejárt	a kulcs lejárati ideje elmúlt	Hozz létre új kulcsot vagy hosszabbíts.
EXTERNAL_NAMESPACE_FORBIDDEN	tiltott külső rendszer névtér	a kérésben megadott externalSystem nem szerepel a kulcs névtér-listájában (vagy érvénytelen formátumú)	Adj meg a kulcshoz tartozó névteret, vagy hagyd el az externalSystem paramétert.
ADDRESS_LIMIT_EXCEEDED	betelt az ügyfél cím-kerete	az ügyfélhez tartozó címek száma elérte a csomag korlátját (a details.limit megmondja, mennyi)	Törölj egy már nem használt címet, vagy válts nagyobb csomagra.
MODULE_NOT_AVAILABLE	a modul nincs a fiók csomagjában	a végpont olyan modult érint, amit az előfizetés nem tartalmaz (a details.module és a details.plan megmondja, melyiket és milyen csomagon). Ma a készlet modul ilyen: a /v1/materials végpontok Pro csomagtól élnek, az olvasók is	A fiók tulajdonosa váltson nagyobb csomagra. A kulcs jogosultságain nem múlik, azok átállítása nem segít.
QUOTE_LIMIT_EXCEEDED	betelt a havi árajánlat keret	a POST /v1/quotes hívás a csomag havi ajánlat-darabszámán túl van (Ingyenes: 3, Alap: 20, Profi és Üzleti: korlátlan). A details.limit a keret, a details.current az eddigi darabszám ebben a hónapban	Várj a hónap fordulójáig (a keret naptári hónaponként nullázódik), vagy a fiók tulajdonosa váltson nagyobb csomagra. Az újrapróbálás ezen a hónapon belül nem segít, ezért 403 és nem 429.

Ezek a hibák a kulcs beállításán múlnak (kivéve a MODULE_NOT_AVAILABLE-t, ami az előfizetésen), és nem múlnak el újrapróbálással. (A visszavont kulcs a REST híváson 401 INVALID_API_KEY hibát ad, lásd a 401 szakaszt.)

404 — Nem található

Kód	Jelentés	Gyakori ok	Teendő
CUSTOMER_NOT_FOUND	nincs ilyen ügyfél	rossz azonosító, vagy a kulcs hatókörén kívüli ügyfél	Ellenőrizd az azonosítót és a kulcs adat hatókörét.
WORKSHEET_NOT_FOUND	nincs ilyen munkalap	rossz azonosító, vagy a kulcs hatókörén kívüli munkalap	Ellenőrizd az azonosítót és a kulcs adat hatókörét.
QUOTE_NOT_FOUND	nincs ilyen árajánlat	rossz azonosító, vagy a kulcs hatókörén kívüli árajánlat (external_system hatókörnél az ajánlat ügyfele a kulcs névterén kívül esik)	Ellenőrizd az azonosítót és a kulcs adat hatókörét.
MATERIAL_NOT_FOUND	nincs ilyen tétel a törzsben	rossz azonosító, vagy időközben törölt tétel	Kérdezd le a GET /v1/materials végponttal a törzset (cikkszámra szűrve is lehet), és onnan vedd az azonosítót.
TEAM_MEMBER_NOT_FOUND	nincs ilyen aktív csapattag	a hozzárendelésben megadott userId nem a fiók csapattagja, vagy már nem aktív	Kérdezd le a GET /v1/team-members végponttal az aktuális névsort, és onnan vedd az azonosítót.
SERVICE_LOCATION_NOT_FOUND	nincs ilyen aktív telephely	a szerviz munkalap serviceLocation mezőjében megadott azonosító vagy név nem illeszkedik aktív telephelyre	A hibaüzenet felsorolja a választható telephelyeket; a pontos azonosítót a GET /v1/service-locations végpont adja.
ADDRESS_NOT_FOUND	nincs ilyen cím az ügyfélnél	a cím-műveletben megadott addressId nem szerepel az ügyfél címei között (például időközben törölték)	Kérdezd le az ügyfelet (GET /v1/customers/{id}), és az addresses tömbből vedd az aktuális azonosítót.
NOT_FOUND	a kért útvonal nem létezik	elgépelt vagy rossz végpont URL	Ellenőrizd a végpont útvonalát.

A hatókörön kívüli erőforrásra szándékosan 404 érkezik (nem 403), hogy a létezés ténye se derüljön ki. Lásd: adat hatókör.

409 — Ütközés

Kód	Jelentés	Gyakori ok	Teendő
IDEMPOTENCY_KEY_REUSE_DIFFERENT_BODY	az Idempotency-Key már szolgált eltérő kéréstörzshöz	ugyanazt a kulcsot más adattal használtad	Használj új Idempotency-Key-t az eltérő kéréshez.
IDEMPOTENCY_KEY_IN_USE	azonos kulcsú kérés épp feldolgozás alatt	párhuzamos kérés ugyanazzal a kulccsal	Várj röviden, majd próbáld újra.
DUPLICATE_EXTERNAL_ID	a külső azonosító már másik ügyfélhez tartozik	ütköző externalId	Ellenőrizd, melyik ügyfélhez tartozik a külső azonosító.
EXTERNAL_ID_AMBIGUOUS	a külső azonosító több élő ügyfélre illeszkedik	(a) több névteres kulcson a keresés két különböző ügyfelet talált; vagy (b) ugyanaz az azonosító több élő ügyfélhez tartozik (duplikált érték)	(a) szűkítsd az externalSystem paraméterrel; (b) tedd egyértelművé a forrásnál (egy azonosító = egy ügyfél).
SERVICE_LOCATION_AMBIGUOUS	a megadott név több telephelyre illeszkedik	a szerviz munkalap serviceLocation.name mezője nem egyértelmű (pl. „soproni műhely“ a „Sopron“ és a „Sopron Műhely“ telephelyre is)	A hibaüzenet felsorolja az illeszkedő telephelyeket; add meg a telephely azonosítóját név helyett.
ADDRESS_PRIMARY_IMMUTABLE	az elsődleges cím nem törölhető	DELETE hívás az ügyfél elsődleges címére	Előbb állíts be másik elsődleges címet (POST /v1/customers/{id}/addresses/{addressId}/primary), utána törölhető a régi.
CONFIRMATION_REQUIRED	emberi megerősítés szükséges	AI célú kulcs végállapotú státuszra váltana	Megerősítés után küldd újra confirmTerminalStatus: true mezővel.

Az IDEMPOTENCY_KEY_IN_USE rövid várakozás után újrapróbálható; a többi 409 a kérés vagy az adat tisztázását igényli.

Az EXTERNAL_ID_AMBIGUOUS két esetet fed le. (1) Több névteres kulcson a keresés két különböző ügyfélre illeszkedik: szűkítsd az externalSystem paraméterrel. (2) Ugyanaz a külső azonosító több élő ügyfélhez tartozik (duplikált érték, például amikor egy azonosító felmondás után új ügyfélhez kerül): ilyenkor az externalSystem nem segít, és a munkalap-generálás is 409-et ad, tehát nem jön létre rossz ügyfélhez munkalap, és új ügyfél sem. A rendszer addig blokkolja az értéket, amíg a forrásnál egyértelművé nem teszed (egy azonosító = egy ügyfél); utána automatikusan a megfelelő ügyfélhez köti, külön beavatkozás nélkül.

429 — Korlát túllépve

Kód	Jelentés	Gyakori ok	Teendő
RATE_LIMIT_EXCEEDED	percenkénti kéréskorlát túllépve	túl sok kérés egy percen belül	Várj a Retry-After fejléc szerint, majd próbáld újra (exponenciális visszalépéssel).
QUOTA_EXCEEDED	havi keret kimerült	elfogyott a havi hívás kereted	Várj a Retry-After szerint (a hónap végéig), vagy válts magasabb csomagra.

Mindkét hiba átmeneti, és a Retry-After figyelembevételével újrapróbálható. A korlátokról lásd az API referenciát.

500 — Szerveroldali hiba

Kód	Jelentés	Teendő
INTERNAL_ERROR	váratlan szerverhiba	Próbáld újra később, exponenciális visszalépéssel. Ha tartósan fennáll, jelezd nekünk a requestId-vel.

Ez a hiba átmeneti lehet, ezért az óvatos újrapróbálás indokolt.

Egyéb kódok

A következő kódok léteznek a rendszerben, de a jelenlegi REST végpontok közvetlenül nem adják vissza őket. Akkor találkozhatsz velük, ha a kulcskezelő felületet vagy későbbi funkciókat is érintesz; a teljesség kedvéért érdemes ismerned őket.

Kód	HTTP	Mikor	Megjegyzés
KEY_REVOKED	403	visszavont kulcs	A REST híváson a visszavont kulcs INVALID_API_KEY (401) hibát ad; ez a kód a kulcskezelő rétegben fordulhat elő.
KEY_LIMIT_EXCEEDED	403	kulcs létrehozása	Akkor, ha új kulcs létrehozásakor eléred a csomag kulcs limitjét. A REST API maga nem hoz létre kulcsot.
AI_USAGE_NOT_ENABLED	403	AI funkció	Az AI célú felhasználás nincs engedélyezve. A jelenlegi REST végpontok nem dobják.
ADDRESS_INCOMPLETE_FOR_INVOICING	409	számlázás	A számlázási folyamat kódja. A REST ügyfél létrehozás szabad szöveges címnél nem ezt, hanem egy nem blokkoló ADDRESS_UNSTRUCTURED figyelmeztetést ad a válasz warnings tömbjében.
MAINTENANCE_MODE	503	karbantartás	Tervezett karbantartási mód jelzése.
CONVERSION_CONFLICT	409	dokumentum-konverzió	Akkor, ha egy árajánlatból, felmérésből vagy bejelentésből már készült munkalap. A REST POST /v1/worksheets mindig új munkalapot hoz létre, forrás-dokumentum nélkül, ezért ezt a kódot nem adja.
GROUPING_CONFLICT	409	eszköz-csoportosítás	A munkalap eszköz-adatai ellentmondásos állapotban vannak. Az alkalmazás eszközkezelő műveleteinek kódja; a REST végpontok nem dobják.
REVISION_CONFLICT	409	egyidejű szerkesztés	A dokumentumot időközben más módosította. Az alkalmazás optimista zárolásának kódja; a REST végpontok nem dobják.