Hibakódok

Az API hibaválaszok megértése és kezelése.

Áttekintés

Az API szabványosított hibaválaszokat ad vissza konkrét hibakódokkal, hogy gyorsan azonosíthassa és megoldhassa a problémákat.

Hibaválasz formátum

Minden hibaválasz ezt a struktúrát követi:

{
  "status": "error",
  "error": {
    "code": "AUTH_1001",
    "message": "Hiányzó hitelesítő adatok",
    "details": "Mind a 'username', mind a 'password' mező kötelező",
    "timestamp": "2025-12-22T10:30:00Z"
  }
}

Mező	Típus	Leírás
`status`	string	Hibaválaszok esetén mindig "error"
`error.code`	string	Egyedi hibaazonosító
`error.message`	string	Ember által olvasható hibaüzenet
`error.details`	string	További kontextus (opcionális)
`error.timestamp`	string	ISO 8601 időbélyeg

Hitelesítési hibák (1000-1099)

Hitelesítő adatokkal és hitelesítéssel kapcsolatos hibák.

Kód	HTTP	Üzenet	Megoldás
`AUTH_1001`	401	Hiányzó hitelesítő adatok	Adja meg mind a felhasználónevet, mind a jelszót a kérésben
`AUTH_1002`	401	Érvénytelen felhasználónév vagy jelszó	Ellenőrizze a hitelesítő adatok helyességét
`AUTH_1003`	403	A fiók ideiglenesen zárolva	Várjon az újbóli próbálkozás előtt, vagy forduljon az ügyfélszolgálathoz

Kvótahibák (1100-1199)

API kvótával és sebességkorlátokkal kapcsolatos hibák.

Kód	HTTP	Üzenet	Megoldás
`QUOTA_1101`	403	Elégtelen API kvóta	Vásároljon több kreditet, vagy ellenőrizze a kvótát
`QUOTA_1102`	429	Túllépte az API kvótát	Várjon a kvóta visszaállításáig, vagy frissítse az előfizetést

Érvényesítési hibák (2000-2099)

Kérés érvényesítésével és bemeneti adatokkal kapcsolatos hibák.

Kód	HTTP	Üzenet	Megoldás
`VAL_2001`	400	Nincs feltöltött fájl	Foglaljon bele egy fájlt a kérésbe
`VAL_2002`	400	Érvénytelen fájlformátum	Használjon támogatott formátumokat: PDF, PNG, JPG, WEBP
`VAL_2003`	400	Több PDF fájl nem engedélyezett	Töltsön fel egyetlen PDF-et vagy több képet
`VAL_2004`	400	A PDF és a képek nem keverhetők	Töltsön fel vagy PDF-et, vagy képeket, nem mindkettőt
`VAL_2005`	400	Nem támogatott nyelvkód	Használjon támogatott nyelvkódot

Feldolgozási hibák (3000-3099)

A dokumentum feldolgozása és az AI elemzés közben előforduló hibák.

Kód	HTTP	Üzenet	Megoldás
`PROC_3001`	500	A dokumentum feldolgozása sikertelen	Ellenőrizze a képminőséget, próbálja újra a kérést
`PROC_3002`	500	A metaadatok kinyerése sikertelen	Győződjön meg róla, hogy a dokumentum olvasható szöveget tartalmaz
`PROC_3003`	500	A paraméterek kinyerése sikertelen	Ellenőrizze, hogy a vérvizsgálat formátuma felismerhető
`PROC_3004`	500	Az értelmezés generálása sikertelen	Próbálja újra a kérést
`PROC_3006`	504	Feldolgozási időtúllépés	Csökkentse a fájlméretet, vagy bontsa több kérésre
`PROC_3007`	500	Az elemzés az újrapróbálkozások után is sikertelen	Várjon, és próbálja újra, vagy forduljon az ügyfélszolgálathoz

Szerverhibák (5000-5099)

Belső szerverhibák és szolgáltatás-elérhetőségi problémák.

Kód	HTTP	Üzenet	Megoldás
`SRV_5001`	500	Belső szerverhiba	Próbálja újra a kérést, forduljon az ügyfélszolgálathoz, ha tartósan fennáll
`SRV_5002`	503	A szolgáltatás ideiglenesen nem elérhető	Várjon, és próbálja újra exponenciális visszalépéssel

Hibakezelési bevált gyakorlatok

Ajánlások

Mindig ellenőrizze a status mezőt — A sikeres válaszokban "status": "success" szerepel
Implementáljon újrapróbálkozási logikát átmeneti hibákhoz (5xx) exponenciális visszalépéssel
Naplózza a hibakódokat hibakereséshez és monitoringhoz
Jelenítsen meg felhasználóbarát üzeneteket a hibakódok alapján
Használjon sandbox végpontokat a hibakezelés teszteléséhez

Példa hibakezelés (JavaScript)

async function analyzeBloodTest(file) {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      body: formData
    });

    const data = await response.json();

    if (data.status === 'error') {
      const errorCode = data.error.code;

      switch (true) {
        case errorCode.startsWith('AUTH_'):
          throw new Error('Hitelesítés sikertelen. Kérjük, ellenőrizze a hitelesítő adatokat.');
        case errorCode.startsWith('QUOTA_'):
          throw new Error('Kvóta túllépve. Kérjük, frissítse előfizetését.');
        case errorCode.startsWith('VAL_'):
          throw new Error('Érvénytelen kérés: ' + data.error.message);
        case errorCode.startsWith('PROC_'):
          // Újrapróbálkozás feldolgozási hibák esetén
          return retryRequest(file);
        default:
          throw new Error('Hiba történt. Kérjük, próbálja újra.');
      }
    }

    return data.data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}