Hibák

Formázási hiba

Minden hiba JSON törzset ad vissza detail mezővel:

{
  "detail": "Human-readable error message"
}

A kérésérvényesítési hibák (422 állapot) esetén a detail mezőszintű hibák tömbje:

{
  "detail": [
    {
      "loc": ["body", "phone_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

---

HTTP állapotkódok

Állapot	Jelentése	Gyakori okok
400	Rossz kérelem	Hiányzó kötelező mezők, érvénytelen paraméterértékek, nem támogatott művelet
401	Jogosulatlan	Hiányzó hitelesítési fejléc, érvénytelen vagy lejárt API-kulcs vagy JWT-token
403	Tilos	Érvényes Credentials, de az erőforrás egy másik szervezethez tartozik
404	Nem található	Az erőforrásazonosító nem létezik, vagy a szervezete számára nem érhető el
409	Konfliktus	Ismétlődő erőforrás (pl. már regisztrált e-mail)
422	Feldolgozhatatlan entitás	A kérés törzse vagy lekérdezési paramétere nem sikerült a séma érvényesítése
500	Belső szerverhiba	Váratlan szerveroldali hiba
501	Nincs végrehajtva	A szolgáltatás a jelenlegi telepítésben nem támogatott

---

Workflow-ellenőrzési hibák

Egy workflow érvényesítésekor (vagy érvénytelen Node-okkal létrehozva) az API strukturált hibákat ad vissza, amelyek meghatározott Node-okra, Edge-ekre vagy mezőkre hivatkoznak:

{
  "errors": [
    {
      "kind": "node",
      "id": "agent-1",
      "field": "data.prompt",
      "message": "Prompt cannot be empty"
    },
    {
      "kind": "edge",
      "id": "edge-3",
      "field": null,
      "message": "Edge target node does not exist"
    },
    {
      "kind": "workflow",
      "id": null,
      "field": null,
      "message": "Workflow must have exactly one Start Call node"
    }
  ]
}

Mező	Típus	Leírás
kind	"node" | "edge" | "workflow"	Mire vonatkozik a hiba
id	String vagy null	Node vagy Edge azonosítója a workflow-definícióból
field	String vagy null	Pontjelölési útvonal az adott mezőhöz (pl. data.prompt)
message	String	A probléma ember által olvasható leírása

---

Telefonhibák

Előfordulhat, hogy a telefonműveletek meghiúsulnak a következő elnevezett hibatípusok valamelyikével, amelyet a detail mezőben ad vissza:

Hiba	Leírás
PROVIDER_MISMATCH	A kérést nem a megfelelő telefonszolgáltatóhoz irányították
WORKFLOW_NOT_FOUND	A bejövő URL-ben lévő workflow ID nem létezik
ACCOUNT_VALIDATION_FAILED	A telefonszolgáltató Credentials adatai érvénytelenek
PHONE_NUMBER_NOT_CONFIGURED	A telefonszám nincs beállítva a telefonfiókjában
SIGNATURE_VALIDATION_FAILED	A Webhook aláírás ellenőrzése nem sikerült (lehetséges, hamisított kérés)
QUOTA_EXCEEDED	Szervezete túllépte a használati kvótát
GENERAL_AUTH_FAILED	Általános hitelesítési hiba a telefonszolgáltatónál

---

Tippek a hibák kezelésére

• Próbálkozzon újra a 500-n exponenciális visszalépéssel – az átmeneti szerverhibák újrapróbálkozáskor megoldódnak.
• Ne próbálkozzon újra a 4xx-vel – ezek olyan problémákat jeleznek a kéréssel kapcsolatban, amelyek nem oldódnak meg maguktól.
• ** Gondosan ellenőrizze a detail mezőt a 422** oldalon – a loc tömb pontosan meghatározza, hogy melyik mező érvényesítése sikertelen.
• Az API-kulcsok biztonságos tárolása – a korábban működő kulcson lévő 401 valószínűleg azt jelenti, hogy a kulcs archiválva lett.