Greške
Kad poziv ne uspe, HTTP status vam kaže o kakvom problemu je reč, a telo gde je. Prvo pročitajte status: to je jedino što ima svaka greška. Izuzetak su endpointi za pakete, jer neuspele redove prijavljuju unutar odgovora 200.
Statusni kodovi#
| Status | Šta znači |
|---|---|
| 200 | Urađeno. Na endpointima za pakete i kad neki redovi ne uspeju; pogledajte Neuspesi unutar 200. |
| 201 | Kreirano, na primer preko POST /customers i POST /warehouses. POST /int/cards vraća 201 i kad je kartica već postojala. |
| 204 | Obrisano. Tela nema. |
| 400 | Zahtev nismo mogli da pročitamo: telo nije ispravan JSON, nedostaje ključ najvišeg nivoa koji endpoint očekuje (stocks na PUT /int/stocks), nedostaje obavezan parametar upita, ili vrednost ima pogrešan tip. |
| 401 | Token nedostaje, neispravan je, istekao je ili je opozvan. Pogledajte Autentifikacija. |
| 404 | Putanja ne postoji, ili zapis nije u vašoj aplikaciji. |
| 406 | Vaše zaglavlje Accept isključuje JSON. Pošaljite application/json ili izostavite zaglavlje. |
| 413 | Telo zahteva je veće od onoga što primamo. Podelite paket. |
| 422 | Zahtev smo pročitali i odbili: polje nije prošlo validaciju, ili ga je odbilo neko pravilo, na primer porudžbina koja već postoji. |
| 500 | Nešto nije uspelo na našoj strani. Pogledajte Kada ponoviti poziv. |
Telo greške#
Većina grešaka stiže kao objekat errors. Svaki ključ imenuje gde je problem, a svaka vrednost je lista poruka:
- Naziv polja, na primer
city, kad polje objekta koji ste poslali nije prošlo validaciju. - Oblast, na primer
Warehouses, uzeta iz ključa poruke:API.Warehouses.NotFoundide podWarehouses. message, kad poruka nema oblast.
Neki odgovori odstupaju od tog oblika:
- 401:
errors.tokensadrži jedan string, ne listu. - 400, 406, 413 i neki 500 koji nastanu pre nego što zahtev stigne do endpointa:
{"errors": {"detail": "Bad Request"}}sa tekstom statusa. - Nekoliko grešaka pravila:
{"error": "<message>"}, u jednini. - 404: nepoznata putanja vraća
[]; zapis koji ne postoji može vratiti prazno telo. - 500 iz endpointa:
{"message": "An unexpected error occurred."}.
Neki odgovori sa greškom šalju se bez zaglavlja Content-Type. Telo čitajte kao JSON bez obzira na zaglavlje.
{
"errors": {
"Warehouses": ["API.Warehouses.NotFound"]
}
}
{
"error": "API.Order.OrderAlreadyExists"
}
{
"errors": {
"detail": "Bad Request"
}
}
Poruke#
Poruke su ključevi kao API.Warehouses.NotFound ili API.Order.AppLocationNotFound: API, oblast, pa šta nije u redu. Kad vaša aplikacija ima prevod ključa na jezik vašeg tokena, dobijate prevod umesto ključa. Validacija jednog objekta odgovara običnim tekstom pravila, na primer can't be blank.
Odlučujte po statusu i ključu, ne po tekstu poruke. Ista greška može stići kao ključ ili kao prevedena rečenica, zavisno od prevoda vaše aplikacije i jezika vašeg tokena. Zapišite celo telo: to nam treba kad nam se obratite.
Greške validacije#
Kad kreirate ili menjate jedan objekat, svako polje koje ne prođe vraća se pod svojim imenom, sa pravilima koja je prekršilo. Magacin bez adrese, grada, poštanskog broja i tržišta odgovara kao u prvom primeru.
Upisi paketa prijavljuju samo prvi neuspeh svake stavke, kao jedan ključ koji imenuje oblast, polje i pravilo. Magacin bez naziva, poslat preko PUT /warehouse, odgovara kao u drugom primeru. Ispravite ga i pošaljite ponovo da vidite sledeći.
Kad vrednost ima pogrešan tip, neki endpointi dodaju listu fields koja imenuje svako polje, tip koji smo očekivali i šta smo dobili.
{
"errors": {
"address_line_1": ["can't be blank"],
"city": ["can't be blank"],
"postcode": ["can't be blank"],
"market_id": ["can't be blank"]
}
}
{
"errors": {
"Warehouses": ["API.Warehouses.NameCantBeBlank"]
}
}
{
"errors": {
"Utils": ["API.Utils.WrongDataType"],
"fields": [
{
"field": "email",
"expected_type": "string",
"received_type": "integer",
"received_value": 5
}
]
}
}
Neuspesi unutar 200#
Endpointi koji primaju listu upisuju šta mogu i kažu vam šta nisu mogli. Status je 200 u oba slučaja, zato uvek pročitajte listu neuspeha:
| Endpoint | Gde su neuspesi |
|---|---|
| PUT /int/stocks | data.failed: red koji ste poslali u input, razlog u error.message. Pogledajte Zalihe. |
| POST /stock/reconcile | data.failed: stavka koju ste poslali u product, razlog u error. Pogledajte Zalihe. |
Pretraga koja ništa ne nađe takođe može vratiti 200: GET /products sa samo jednim code, barcode, slug ili id vraća {"data": {}}.
Kada ponoviti poziv#
- 4xx: ne šaljite isti zahtev ponovo. Ispravite ono što telo navodi, pa ga pošaljite.
- 500 i mrežne greške: ponovite posle pauze i čekajte svaki put duže. Ako i dalje ne uspeva, pišite na [email protected] i pošaljite zahtev i odgovor.
- Znajte šta ponovni pokušaj radi pre nego što ga automatizujete.
POST /int/productsuparuje proizvode po šifri, pa ih ponovni pokušaj menja umesto da ih pravi dvaput; samo se slike ponovo dodaju.PUT /int/stocksdodaje količine, pa ponovni pokušaj posle isteka vremena, kad je prvi zahtev ipak prošao, dodaje ih dvaput: prvo proverite ukupno stanje prekoGET /stocks/aggregate, ili koristite usklađivanje.
Povezano#
- Autentifikacija: svaka vrednost
401i šta znači. - Zalihe: rezultati po redu u praksi.
- Paginacija i filtriranje: parametri upita koje endpointi za liste primaju.