Hibák

A Sursa HTTP-állapotkódokkal jelzi, hogy egy kérés sikeres volt-e, és stabil hibakóddal azt, hogy miért nem. Minden hibaválasz azonos szerkezetű:

{
  "detail": "the cursor is malformed or was issued for different filters",
  "error": {
    "code": "api.cursor_invalid",
    "message": "the cursor is malformed or was issued for different filters",
    "details": {"parameter": "cursor"},
    "request_id": "01JB7Q2M4X9V3K8T5N6P0R1S2A",
    "doc_url": "https://developers.sursa.com/errors/api.cursor_invalid"
  }
}

Mező	Jelentése
`error.code`	Stabil kód `<area>.<reason>` alakban. Erre építsd a kódod elágazásait.
`error.message`	Olvasható angol nyelvű magyarázat. Bármikor átfogalmazódhat; ne elemezd.
`error.details`	A hiba strukturált adatai, például a paraméter, egy korlát, vagy hogy mikor érdemes újrapróbálni. A mezői a kódtól függenek.
`error.request_id`	A kérés azonosítója, ugyanaz, mint az `X-Request-Id` válaszfejlécben.
`error.doc_url`	A kódról szóló oldal ezen a portálon.
`detail`	A hiba korábbi alakja, a meglévő integrációk kedvéért megtartva. Az új kód az `error` mezőt olvassa.

Minden kódnak saját oldala van a Hibakódok alatt, a HTTP-állapotkódjával, a details mezőivel és az őt visszaadó végpontokkal. Az API-referencia minden végpontoldala felsorolja, milyen kódokat adhat vissza az adott végpont.

HTTP-állapotkódok

Állapotkód	Jelentése
`200`, `201`, `202`, `204`	A kérés sikeres volt. A `202` azt jelenti, hogy a Sursa befogadta a kérést, és a feldolgozása még tart.
`400`	A kérés hibásan formázott: rossz paraméter, kurzor, `metadata` vagy `Idempotency-Key`. Javítsd a kérést.
`401`	Nincs érvényes kulcs. Lásd: Hitelesítés.
`402`	A szervezet elérte a csomagja egy korlátját, például a kártyák számát vagy a tárhelyet.
`403`	A kulcs érvényes, de ehhez nincs engedélye: hiányzik egy szerepkör, egy hatókör vagy egy csomagfunkció.
`404`	Az objektum nem létezik, vagy a kulcs nem láthatja.
`409`	A kérés ütközik a jelenlegi állapottal: ismétlődő `external_id`, nyitott szinkronizálás, vagy még fut egy kérés ugyanazzal az `Idempotency-Key` értékkel.
`410`	Az objektum lejárt, például egy feltöltés 24 óra után, vagy az útvonalat kivezették.
`413`	A törzs vagy a fájl túl nagy.
`415`	A fájltípus nem támogatott, vagy a tartalma nem egyezik a nevével.
`422`	A kérés formailag helyes, de érvénytelen: hiányzik egy mező, vagy egy érték a tartományon kívül esik.
`429`	Túl sok kérés érkezett, vagy elfogyott egy kvóta. Lásd: Gyakorisági korlátok és kvóták.
`500`, `502`, `503`, `504`	Probléma a Sursa oldalán. Próbáld újra később.

Érvényesítési hibák

A validation.failed kódú 422 válasznál a detail felsorol minden hibás mezőt, mindegyiket a helyével együtt:

{
  "detail": [
    {"loc": ["body", "title"], "msg": "String should have at least 1 character", "type": "string_too_short"}
  ],
  "error": {"code": "validation.failed", "message": "request validation failed", "request_id": "01JB7…"}
}

Mely hibákat érdemes újrapróbálni

Hiba	Újrapróbálás?
Hálózati hiba vagy időtúllépés, nincs válasz	Igen, ugyanazzal az `Idempotency-Key` értékkel.
`429`	Igen, a `Retry-After` fejlécben megadott másodpercek után.
`500`, `502`, `503`, `504`	Igen, exponenciális várakozással: 1 s, 2 s, 4 s… legfeljebb egy percig, véletlen szórással.
`409` `api.idempotency_in_progress`	Igen, a `Retry-After` után: az ezzel a kulccsal küldött első kérés még fut.
Bármely más `4xx`	Nem. Ugyanez a kérés újra sikertelen lesz; előbb javítsd ki.

A POST és a PATCH kéréseket csak Idempotency-Key fejléccel próbáld újra, hogy egy elveszett válasz utáni újrapróbálkozás ne hozzon létre második objektumot. A GET, a PUT és a DELETE kérés változtatás nélkül, biztonságosan újrapróbálható.

// Retries a request on network errors, 429 and 5xx. The same Idempotency-Key is sent on every attempt.
async function withRetries(send, attempts = 5) {
  for (let attempt = 1; ; attempt++) {
    let response;
    try {
      response = await send();
    } catch (error) {
      if (attempt >= attempts) throw error;
    }
    if (response && response.status !== 429 && response.status < 500) return response;
    if (attempt >= attempts) return response;
    const retryAfter = Number(response?.headers.get("Retry-After"));
    const backoff = Math.min(60, 2 ** (attempt - 1)) * (0.8 + Math.random() * 0.4);
    await new Promise((resolve) => setTimeout(resolve, 1000 * (retryAfter || backoff)));
  }
}

const key = crypto.randomUUID();
const response = await withRetries(() =>
  fetch("https://api.sursa.com/v1/cards/text", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SURSA_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": key,
    },
    body: JSON.stringify({ title: "Refund policy", body_markdown: "Refunds take 14 days." }),
  }),
);

Probléma jelentése

Minden válasznak, akár sikeres, akár nem, van X-Request-Id fejléce, és minden hibában ugyanez az érték szerepel az error.request_id mezőben. Naplózd a kérésről vezetett saját bejegyzéseddel együtt. Ha egy kérés miatt az ügyfélszolgálathoz fordulsz, küldd el a kérés azonosítóját: ez közvetlenül a kérés bejegyzéséhez vezet.

Ismeretlen kódok kezelése

Az API bármely verziójában megjelenhetnek új hibakódok. Az ismeretlen kódot a HTTP-állapotkódja szerint kezeld: az ismeretlen 4xx kódot olyan kérésként, amely ebben a formában nem fog sikerülni, az ismeretlen 5xx kódot átmeneti problémaként.