API atsakymai ir klaidos – ką reiškia ir ką daryti?

API atsakymai ir klaidos – ką reiškia ir ką daryti?

Kiekviena BSS API užklausa grąžina HTTP statusą, pagal kurį galima suprasti, ar užklausa įvykdyta sėkmingai, ar ją vykdant įvyko klaida. Gavus klaidą svarbu vertinti ne tik HTTP statusą, bet ir visą API grąžintą informaciją – joje gali būti nurodyta konkreti problemos priežastis.

Svarbiausia taisyklė: pirmiausia patikrinkite HTTP statusą, o jei atsakyme grąžintas klaidos turinys – perskaitykite message, errors ir errorMessages. Jei konkretaus metodo atsakyme pateikiamas stabilus klaidos kodas, integracijos logiką rekomenduojama grįsti kodu. Vien prie klaidos pranešimo teksto integracijos logikos rišti nerekomenduojama, nes tekstas gali keistis.

Sėkmingi API atsakymai

Statusas Ką reiškia? Ką daryti?
200 OK Užklausa sėkmingai įvykdyta ir atsakyme grąžinti duomenys. Naudokite response body grąžintus duomenis. Priklausomai nuo metodo gali būti grąžintas vienas objektas, objektų sąrašas arba puslapiuoti rezultatai.
201 Created Naujas objektas sėkmingai sukurtas. Response body negrąžinamas. Atsakymo Location antraštėje pateikiamas naujai sukurto objekto adresas, pagal kurį galima identifikuoti sukurtą objektą ir panaudoti jo reikšmę kitame metode. Pavyzdžiui: sukūrus sąskaitą ją patvirtinti.
202 Accepted Užklausa priimta vykdyti, tačiau jos apdorojimas dar nebaigtas. Nelaikykite 202 galutiniu sėkmingos operacijos rezultatu. Jei metodas vykdomas asinchroniškai, galutinį rezultatą reikia nustatyti pagal tam metodui numatytą apdorojimo mechanizmą. Jei rezultatas perduodamas per Webhook, žr. atskirą instrukciją „Webhook pranešimai ir apdorojimo rezultatai“.
204 No Content Užklausa sėkmingai įvykdyta, tačiau API atsakyme negrąžina papildomų duomenų. 204 laikykite sėkmingu rezultatu. Tuščias response body šiuo atveju yra normalu ir nereiškia klaidos.

Klaidų atsakymai

Statusas Ką reiškia? Ką pirmiausia tikrinti?
400 Bad Request API gavo užklausą su netinkamais duomenimis. Perskaitykite grąžintą klaidos informaciją. Joje gali būti nurodytas konkretus laukas, objektas ar kita priežastis, dėl kurios užklausa negali būti įvykdyta. Pataisykite siunčiamus duomenis ir užklausą kartokite tik pašalinę nurodytą problemą.
401 Unauthorized Užklausai trūksta galiojančios autentifikacijos informacijos. Patikrinkite, ar perduodamas galiojantis AccessToken. Jei jo galiojimas pasibaigė, gaukite naują AccessToken naudodami RefreshToken. Plačiau žr. instrukciją „Prisijungimas prie BSS API ir tokenų atnaujinimas“.
403 Forbidden Autentifikacija atlikta, tačiau nėra teisių pasiekti prašomą turinį ar atlikti veiksmą. Kreipkitės į BSS konsultantus, kad būtų suteiktos arba pakoreguotos reikalingos rolės prieigai prie konkretaus API veiksmo ar duomenų.
404 Not Found Prašomas objektas arba resursas nerastas. Patikrinkite užklausoje naudojamą objekto identifikatorių ir API adresą. 404 atsakymas response body neturi, todėl pirmiausia tikrinkite pačios užklausos parametrus.
429 Too Many Requests Užklausai pritaikytas API užklausų ribojimas. Jei atsakyme grąžinta Retry-After antraštė, palaukite joje nurodytą laiką ir tik tada bandykite užklausą kartoti. Integracija turi būti paruošta tokią situaciją apdoroti automatiškai.
500 Internal Server Error Vykdant užklausą BSS pusėje įvyko sistemos klaida. Perskaitykite grąžintą message, jei jis pateikiamas. Jei užklausa suformuota teisingai ir klaida kartojasi, kreipkitės į BSS konsultantus bei pateikite informaciją apie vykdytą užklausą.

Kaip skaityti 400 klaidos atsakymą?

Kai API gauna netinkamus duomenis, klaidos atsakyme gali būti pateikiami šie laukai:

Laukas Ką jame rasite?
message Bendrą informaciją apie užklausos vykdymo rezultatą arba klaidą.
errors Klaidas, susietas su konkrečiais siunčiamais laukais.
errorMessages Papildomus klaidos paaiškinimus.

Praktiškai: gavę 400, neapsiribokite vien užrašu „Bad Request“. Perskaitykite visą grąžintą atsakymą ir ieškokite konkrečios priežasties – kokia reikšmė netinkama, kokio objekto nepavyko rasti ar kokio reikalavimo užklausa neatitinka.

202 Accepted – ką reiškia asinchroninis apdorojimas

202 Accepted nėra klaida. Jis reiškia, kad užklausa priimta, tačiau jos apdorojimas dar nebaigtas. Gavus 202, nereikėtų laikyti operacijos sėkmingai užbaigta. Tolimesnis veiksmas priklauso nuo konkretaus API metodo. Kai kuriuose metoduose rezultatą reikia tikrinti pakartotinai kviečiant tą patį metodą: kol apdorojimas vyksta, grąžinamas 202, o paruošus rezultatą – 200 OK. Toks veikimas, pavyzdžiui, aprašytas partnerių skolų masiniame metode. Kitais atvejais galutinis rezultatas gali būti perduodamas per Webhook. Tokiu atveju žr. atskirą instrukciją „Webhook pranešimai ir apdorojimo rezultatai“.

Svarbu: nėra vienos bendros taisyklės, po kiek laiko kartoti užklausą ar ar apskritai ją reikia kartoti. Visada vadovaukitės konkretaus metodo aprašymu.