Kļūdas

Ar HTTP statusa kodiem Sursa norāda, vai pieprasījums izdevās, bet ar stabilu kļūdas kodu – kāpēc tas neizdevās. Visām kļūdu atbildēm ir vienāda struktūra:

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

Lauks	Nozīme
`error.code`	Stabils kods formā `<area>.<reason>`. Pēc tā izvēlieties, kā rīkoties savā kodā.
`error.message`	Cilvēkam lasāms skaidrojums angļu valodā. To var pārformulēt jebkurā laikā; neparsējiet to.
`error.details`	Strukturēti fakti par kļūdu, piemēram, parametrs, limits vai laiks, kad atkārtot. Tā lauki ir atkarīgi no koda.
`error.request_id`	Šī pieprasījuma ID, tāds pats kā atbildes galvenē `X-Request-Id`.
`error.doc_url`	Šī portāla lapa par šo kodu.
`detail`	Agrākā kļūdas forma, kas saglabāta esošajām integrācijām. Jaunā kodā lasiet `error`.

Katram kodam ir sava lapa sadaļā Kļūdu kodi ar tā HTTP statusu, details laukiem un operācijām, kas to atgriež. Katras operācijas lapā API rokasgrāmatā ir uzskaitīti kodi, ko šī operācija var atgriezt.

HTTP statusi

Statuss	Nozīme
`200`, `201`, `202`, `204`	Pieprasījums izdevās. `202` nozīmē, ka tas ir pieņemts un vēl tiek apstrādāts.
`400`	Pieprasījums ir nepareizi veidots: nepareizs parametrs, kursors, `metadata` vai `Idempotency-Key`. Izlabojiet pieprasījumu.
`401`	Nav derīgas atslēgas. Sk. Autentifikācija.
`402`	Sasniegts organizācijas plāna limits, piemēram, kartīšu skaita vai krātuves apjoma limits.
`403`	Atslēga ir derīga, bet tai nav atļauts to darīt: trūkst lomas, tvēruma vai plāna iespējas.
`404`	Objekts neeksistē, vai atslēgai nav atļauts to redzēt.
`409`	Pieprasījums ir pretrunā ar pašreizējo stāvokli: dublēts `external_id`, atvērta sinhronizācija, vēl tiek izpildīts pieprasījums ar to pašu `Idempotency-Key`.
`410`	Objektam beidzies derīguma termiņš, piemēram, augšupielādei pēc 24 stundām, vai maršruts ir izbeigts.
`413`	Saturs vai fails ir pārāk liels.
`415`	Faila tips netiek atbalstīts, vai tā saturs neatbilst nosaukumam.
`422`	Pieprasījums ir pareizi veidots, bet nederīgs: trūkst lauka vai vērtība ir ārpus diapazona.
`429`	Pārāk daudz pieprasījumu, vai kvota ir izlietota. Sk. Pieprasījumu biežuma limiti un kvotas.
`500`, `502`, `503`, `504`	Problēma Sursas pusē. Atkārtojiet vēlāk.

Validācijas kļūdas

Ja atbilde ir 422 ar kodu validation.failed, detail uzskaita visus laukus ar kļūdām un katra lauka atrašanās vietu:

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

Kuras kļūdas atkārtot

Kļūda	Atkārtot?
Tīkla kļūda vai noildze, atbildes nav	Jā, ar to pašu `Idempotency-Key`.
`429`	Jā, pēc `Retry-After` norādītā sekunžu skaita.
`500`, `502`, `503`, `504`	Jā, ar eksponenciāli pieaugošām pauzēm: 1 s, 2 s, 4 s… līdz minūtei, ar nejaušu novirzi (jitter).
`409` `api.idempotency_in_progress`	Jā, pēc `Retry-After`: pirmais pieprasījums ar šo atslēgu vēl tiek izpildīts.
Jebkura cita `4xx`	Nē. Tas pats pieprasījums atkal neizdosies; vispirms to izlabojiet.

POST un PATCH pieprasījumus atkārtojiet tikai ar Idempotency-Key, lai atkārtojums pēc pazaudētas atbildes nevarētu izveidot otru objektu. GET, PUT un DELETE var droši atkārtot tādus, kādi tie ir.

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

Ziņošana par problēmu

Katrai atbildei, veiksmīgai vai ne, ir galvene X-Request-Id, un katrai kļūdai tā pati vērtība ir laukā error.request_id. Ierakstiet to žurnālā kopā ar savu ierakstu par pieprasījumu. Kad sazināties ar atbalsta dienestu par kādu pieprasījumu, nosūtiet tā ID: tas ved tieši uz šī pieprasījuma ierakstu.

Nezināmu kodu apstrāde

Jauni kļūdu kodi var parādīties jebkurā API versijā. Nezināmu kodu apstrādājiet pēc tā HTTP statusa: nezināmu 4xx – kā pieprasījumu, kas tādā veidā neizdosies, nezināmu 5xx – kā īslaicīgu problēmu.