Vead

Sursa näitab HTTP olekukoodiga, kas päring õnnestus, ja püsiva veakoodiga, miks see ei õnnestunud. Igal veavastusel on sama kuju:

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

Väli	Tähendus
`error.code`	Püsiv kood kujul `<area>.<reason>`. Tehke oma koodis otsused selle järgi.
`error.message`	Loetav ingliskeelne selgitus. Selle sõnastus võib igal ajal muutuda; ärge seda parsige.
`error.details`	Struktureeritud faktid vea kohta, näiteks parameeter, limiit või see, millal uuesti proovida. Selle väljad sõltuvad koodist.
`error.request_id`	Selle päringu ID, sama mis vastuse päises `X-Request-Id`.
`error.doc_url`	Selle koodi leht selles portaalis.
`detail`	Vea varasem kuju, mis on alles olemasolevate integratsioonide jaoks. Uues koodis lugege välja `error`.

Igal koodil on oma leht jaotises Veakoodid: seal on koodi HTTP-olek, välja details väljad ja lõpp-punktid, mis selle tagastavad. API teatmikus loetleb iga lõpp-punkti leht koodid, mida see lõpp-punkt võib tagastada.

HTTP-olekud

Olek	Tähendus
`200`, `201`, `202`, `204`	Päring õnnestus. `202` tähendab, et päring võeti vastu ja selle töötlemine veel käib.
`400`	Päring on vigane: vale parameeter, kursor, väli `metadata` või päis `Idempotency-Key`. Parandage päring.
`401`	Kehtivat võtit ei ole. Vt Autentimine.
`402`	Organisatsiooni paketi limiit on täis, näiteks kaartide arv või salvestusruum.
`403`	Võti kehtib, kuid sellel ei ole lubatud seda teha: puudub roll, ulatus või paketi funktsioon.
`404`	Objekti ei ole olemas või võtmel ei ole lubatud seda näha.
`409`	Päring on vastuolus praeguse olekuga: korduv `external_id`, avatud sünkroonimine või veel pooleli olev päring, millel on sama `Idempotency-Key`.
`410`	Objekti kehtivus on lõppenud, näiteks üleslaadimisel 24 tunni möödudes, või tee on kasutusest kõrvaldatud.
`413`	Keha või fail on liiga suur.
`415`	Failitüüpi ei toetata või faili sisu ei vasta selle nimele.
`422`	Päring on õigesti vormistatud, kuid kehtetu: puudub väli või väärtus on lubatud vahemikust väljas.
`429`	Päringuid on liiga palju või kvoot on ära kasutatud. Vt Sageduspiirangud ja kvoodid.
`500`, `502`, `503`, `504`	Probleem on Sursa poolel. Proovige hiljem uuesti.

Valideerimisvead

Kui vastus on 422 koodiga validation.failed, loetleb detail kõik väljad, mis valideerimist ei läbinud, ja iga välja asukoha:

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

Milliseid vigu tasub uuesti proovida

Viga	Kas proovida uuesti?
Võrguviga või ajalõpp, vastust ei tulnud	Jah, sama päisega `Idempotency-Key`.
`429`	Jah, kui päises `Retry-After` antud sekundid on möödunud.
`500`, `502`, `503`, `504`	Jah, eksponentsiaalse ooteajaga: 1 s, 2 s, 4 s… kuni minutini, juhusliku hajutusega.
`409` `api.idempotency_in_progress`	Jah, kui päises `Retry-After` antud aeg on möödunud: esimene selle võtmega päring on veel pooleli.
Mis tahes muu `4xx`	Ei. Sama päring ebaõnnestub uuesti; parandage see kõigepealt.

Korrake päringuid POST ja PATCH ainult päisega Idempotency-Key, et korduskatse pärast kaotsi läinud vastust ei saaks luua teist objekti. Päringuid GET, PUT ja DELETE võib turvaliselt korrata muutmata kujul.

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

Probleemist teatamine

Igal vastusel, nii edukal kui ka vigasel, on päis X-Request-Id ja igal veal on sama väärtus väljal error.request_id. Logige see koos oma kirjega päringu kohta. Kui pöördute päringu asjus toe poole, saatke selle päringu ID: see viib otse selle päringu kirjeni.

Tundmatute koodide käsitlemine

Uued veakoodid võivad ilmuda API mis tahes versioonis. Käsitlege tundmatut koodi selle HTTP-oleku järgi: tundmatu olek 4xx tähendab päringut, mis sellisel kujul ei õnnestu, ja tundmatu olek 5xx ajutist probleemi.