Chyby

Sursa používa stavové kódy HTTP na to, aby povedala, či požiadavka uspela, a stabilný chybový kód na to, aby povedala, prečo neuspela. Každá chybová odpoveď má rovnaký tvar:

{
  "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"
  }
}

Pole	Význam
`error.code`	Stabilný kód v tvare `<area>.<reason>`. Podľa neho vetvite svoj kód.
`error.message`	Čitateľné vysvetlenie v angličtine. Jeho znenie sa môže kedykoľvek zmeniť; neanalyzujte ho.
`error.details`	Štruktúrované údaje o chybe, napríklad parameter, limit alebo kedy opakovať. Jeho polia závisia od kódu.
`error.request_id`	ID tejto požiadavky, rovnaké ako hlavička odpovede `X-Request-Id`.
`error.doc_url`	Stránka o tomto kóde na tomto portáli.
`detail`	Starší tvar chyby ponechaný pre existujúce integrácie. Nový kód by mal čítať `error`.

Každý kód má vlastnú stránku v časti Chybové kódy so stavovým kódom HTTP, poliami details a operáciami, ktoré ho vracajú. Stránka každej operácie v referencii API uvádza kódy, ktoré táto operácia môže vrátiť.

Stavové kódy HTTP

Stav	Význam
`200`, `201`, `202`, `204`	Požiadavka uspela. `202` znamená, že bola prijatá a ešte sa spracúva.
`400`	Požiadavka má nesprávny tvar: chybný parameter, kurzor, `metadata` alebo `Idempotency-Key`. Opravte požiadavku.
`401`	Chýba platný kľúč. Pozri Autentifikácia.
`402`	Dosiahol sa limit tarify organizácie, napríklad počet kariet alebo úložisko.
`403`	Kľúč je platný, ale toto robiť nesmie: chýba rola, rozsah alebo funkcia tarify.
`404`	Objekt neexistuje alebo ho kľúč nesmie vidieť.
`409`	Požiadavka je v rozpore s aktuálnym stavom: duplicitné `external_id`, otvorená synchronizácia, stále prebiehajúca požiadavka s rovnakým `Idempotency-Key`.
`410`	Platnosť objektu vypršala, napríklad nahrávania po 24 hodinách, alebo bola cesta vyradená.
`413`	Telo alebo súbor je príliš veľký.
`415`	Typ súboru nie je podporovaný alebo jeho obsah nezodpovedá názvu.
`422`	Požiadavka má správny tvar, ale je neplatná: chýbajúce pole alebo hodnota mimo rozsahu.
`429`	Príliš veľa požiadaviek alebo je vyčerpaná kvóta. Pozri Limity frekvencie a kvóty.
`500`, `502`, `503`, `504`	Problém na strane Sursy. Opakujte neskôr.

Chyby validácie

Pri 422 s kódom validation.failed uvádza detail každé pole, ktoré neprešlo validáciou, spolu s jeho umiestnením:

{
  "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…"}
}

Ktoré chyby opakovať

Chyba	Opakovať?
Sieťová chyba alebo vypršanie časového limitu, žiadna odpoveď	Áno, s rovnakým `Idempotency-Key`.
`429`	Áno, po počte sekúnd z `Retry-After`.
`500`, `502`, `503`, `504`	Áno, s exponenciálne rastúcim oneskorením: 1 s, 2 s, 4 s… až do minúty, s náhodným rozptylom.
`409` `api.idempotency_in_progress`	Áno, po `Retry-After`: prvá požiadavka s týmto kľúčom ešte prebieha.
Akýkoľvek iný `4xx`	Nie. Rovnaká požiadavka znova zlyhá; najprv ju opravte.

Požiadavky POST a PATCH opakujte len s Idempotency-Key, aby opakovanie po stratenej odpovedi nemohlo vytvoriť druhý objekt. GET, PUT a DELETE možno bezpečne opakovať tak, ako sú.

// 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." }),
  }),
);

Nahlásenie problému

Každá odpoveď, úspešná aj neúspešná, má hlavičku X-Request-Id a každá chyba má rovnakú hodnotu v error.request_id. Zapisujte ju do logu spolu s vlastným záznamom o požiadavke. Keď sa na podporu obraciate v súvislosti s požiadavkou, pošlite jej ID požiadavky: vedie priamo k záznamu o tejto požiadavke.

Spracovanie neznámych kódov

Nové chybové kódy sa môžu objaviť v ktorejkoľvek verzii API. Neznámy kód spracujte podľa stavového kódu HTTP: neznámy 4xx ako požiadavku, ktorá v tejto podobe neuspeje, neznámy 5xx ako dočasný problém.