Što znače poruke o grešci
Što koja poruka znači, koji status ide uz nju i što je sigurno pokušati ponovno.
Kad program pošalje nešto što nema smisla, odgovor mora reći što je pošlo po zlu. Ovdje je popis najčešćih odgovora, objašnjenih tako da se vidi što ih je izazvalo i što je sigurno pokušati ponovno.
{
"statusCode": 400,
"message": "Ovaj modul nije uključen za tvrtku.",
"key": "errors.moduleDisabled",
"locale": "hr"
}
statusCode— HTTP status; po njemu se odlučuje o ponovnom pokušaju.message— rečenica za čovjeka, na jeziku zahtjeva (Accept-Language).key— stabilan strojni kod; ne mijenja se i ne prevodi se. Na njemu se temelji logika.locale— jezik na kojem jemessagenapisan.
HTTP statusi
| Status | Znači | Ponoviti? |
|---|---|---|
| 200 | Uspjeh | — |
| 201 | Stvoreno (vožnja, ključ, otkazivanje) | — |
| 400 | Zahtjev nije ispravan: polje, datum, modul, stanje tvrtke | ne, ispravi zahtjev |
| 401 | Ključ nije prepoznat ili je sesija istekla | ne, provjeri ključ |
| 403 | Prepoznat, ali ne smije: opseg, adresa, neaktivna tvrtka | ne |
| 404 | Nema zapisa u vašoj tvrtki | ne |
| 409 | Stanje se promijenilo (vožnja je već završena) | ne, dohvati stanje |
| 429 | Prekoračeno ograničenje prometa | da, po Retry-After |
| 5xx | Greška na našoj strani | da, s linearnim čekanjem |
404. Odgovor 403 rekao bi da zapis postoji — a to je podatak o drugoj tvrtki koji ne smije izaći.Najvažniji kodovi
| Kod | Status | Znači | Rješenje |
|---|---|---|---|
errors.invalidApiKey | 401 | Ključ nije prepoznat | Provjerite zaglavlje i ključ |
errors.apiKeyRevoked | 403 | Ključ je opozvan | Izdajte novi ključ |
errors.apiKeyExpired | 403 | Ključu je istekao rok | Izdajte novi ključ s novim rokom |
errors.apiKeyIpNotAllowed | 403 | Adresa nije na popisu | Dodajte adresu ili koristite drugi izvor |
errors.forbidden | 403 | Nedostaje opseg | Dodajte opseg ključu |
errors.moduleDisabled | 400 | Modul nije uključen za tvrtku | Uključite addon.api_access |
errors.tenantInactive | 403 | Tvrtka nije aktivna | Provjerite pretplatu tvrtke |
errors.launchNotReady | 400 | Tvrtka nije spremna za pogon | Dovršite 12 provjera spremnosti |
errors.apiRideNeedsRoute | 400 | Nema dovoljno podataka za rutu | Pošaljite obje koordinate |
errors.externalIdInvalid | 400 | Neispravna vanjska oznaka | Dopuštena su slova, brojke i ._:- |
errors.invalidPhone | 400 | Neispravan telefon | Pošaljite + i 6–30 znakova |
errors.tooManyStops | 400 | Previše međuzaustavljanja | Najviše 16 |
errors.rideTransitionNotAllowed | 409 | Prijelaz stanja nije dopušten | Dohvatite trenutno stanje |
errors.invalidDate | 400 | Datum nije u obliku YYYY-MM-DD | Ispravite format |
errors.invalidDateRange | 400 | from je poslije to | Zamijenite granice |
errors.statsRangeTooLong | 400 | Raspon je dulji od 92 dana | Podijelite na dva poziva |
errors.tooManyRequests | 429 | Prekoračeno ograničenje | Čekajte Retry-After sekundi |
errors.webhookEventsRequired | 400 | Webhook bez događaja | Odaberite barem jedan događaj |
errors.webhookEventUnknown | 400 | Nepoznat događaj | Koristite jedno od četiri imena |
Ovo je izbor iz kataloga: u kodu postoji 739 različitih ključeva grešaka. Svi slijede isto pravilo imenovanja errors.<kratkiNaziv>, pa se nepoznati ključ može sigurno prikazati korisniku uz opći tekst.
Ograničenja prometa
| Kanal | Ograničenje | Ključ |
|---|---|---|
Partner API /v1 | 120 zahtjeva u minuti po ključu | API ključ |
| Ostali zahtjevi | 120 u 60 sekundi po izvoru | adresa i sesija |
| Prijava | strože, po adresi i računu | adresa + račun |
Odgovor 429 nosi zaglavlje Retry-After u sekundama. Preporučeni uzorak je linearno čekanje s malom slučajnom odgodom; ponovni pokušaj bez čekanja samo produljuje blokadu.
async function call(url, options, attempt = 0) {
const response = await fetch(url, options);
if (response.status === 429 && attempt < 5) {
const wait = Number(response.headers.get('Retry-After') || 1) * 1000;
await new Promise((done) => setTimeout(done, wait + Math.random() * 250));
return call(url, options, attempt + 1);
}
if (response.status >= 500 && attempt < 3) {
await new Promise((done) => setTimeout(done, 500 * (attempt + 1)));
return call(url, options, attempt + 1);
}
return response;
}
Idempotencija i ponovni pokušaji
- Naručivanje (
POST /v1/rides) je idempotentno prekoexternalId: isti zahtjev dvaput vraća istu vožnju sreplayed: true. - Otkazivanje je idempotentno po prirodi: drugo otkazivanje završene vožnje vraća
409, što je očekivano stanje, ne greška. - Čitanja (
GET) se smiju ponavljati bez ograničenja; jedina posljedica je potrošeno ograničenje prometa. - Webhookovi stižu barem jednom: deduplicirajte po
iddogađaja.
Jezik greške
Zaglavlje Accept-Language odabire jezik message polja (hr, en, sl, de). key se ne mijenja — na njemu se temelji logika. Ako jezika nema, odgovor je na hrvatskom uz locale: "hr".