Driveoskatalog platforme

Š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.

jsonoblik greške
{
  "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 je message napisan.

HTTP statusi

StatusZnačiPonoviti?
200Uspjeh—
201Stvoreno (vožnja, ključ, otkazivanje)—
400Zahtjev nije ispravan: polje, datum, modul, stanje tvrtkene, ispravi zahtjev
401Ključ nije prepoznat ili je sesija isteklane, provjeri ključ
403Prepoznat, ali ne smije: opseg, adresa, neaktivna tvrtkane
404Nema zapisa u vašoj tvrtkine
409Stanje se promijenilo (vožnja je već završena)ne, dohvati stanje
429Prekoračeno ograničenje prometada, po Retry-After
5xxGreška na našoj stranida, s linearnim čekanjem
Zašto 404, a ne 403Zahtjev za tuđu vožnju vraća 404. Odgovor 403 rekao bi da zapis postoji — a to je podatak o drugoj tvrtki koji ne smije izaći.

Najvažniji kodovi

KodStatusZnačiRješenje
errors.invalidApiKey401Ključ nije prepoznatProvjerite zaglavlje i ključ
errors.apiKeyRevoked403Ključ je opozvanIzdajte novi ključ
errors.apiKeyExpired403Ključu je istekao rokIzdajte novi ključ s novim rokom
errors.apiKeyIpNotAllowed403Adresa nije na popisuDodajte adresu ili koristite drugi izvor
errors.forbidden403Nedostaje opsegDodajte opseg ključu
errors.moduleDisabled400Modul nije uključen za tvrtkuUključite addon.api_access
errors.tenantInactive403Tvrtka nije aktivnaProvjerite pretplatu tvrtke
errors.launchNotReady400Tvrtka nije spremna za pogonDovršite 12 provjera spremnosti
errors.apiRideNeedsRoute400Nema dovoljno podataka za rutuPošaljite obje koordinate
errors.externalIdInvalid400Neispravna vanjska oznakaDopuštena su slova, brojke i ._:-
errors.invalidPhone400Neispravan telefonPošaljite + i 6–30 znakova
errors.tooManyStops400Previše međuzaustavljanjaNajviše 16
errors.rideTransitionNotAllowed409Prijelaz stanja nije dopuštenDohvatite trenutno stanje
errors.invalidDate400Datum nije u obliku YYYY-MM-DDIspravite format
errors.invalidDateRange400from je poslije toZamijenite granice
errors.statsRangeTooLong400Raspon je dulji od 92 danaPodijelite na dva poziva
errors.tooManyRequests429Prekoračeno ograničenjeČekajte Retry-After sekundi
errors.webhookEventsRequired400Webhook bez događajaOdaberite barem jedan događaj
errors.webhookEventUnknown400Nepoznat događajKoristite 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

KanalOgraničenjeKljuč
Partner API /v1120 zahtjeva u minuti po ključuAPI ključ
Ostali zahtjevi120 u 60 sekundi po izvoruadresa i sesija
Prijavastrože, po adresi i računuadresa + 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.

javascriptponovni pokušaj koji poštuje ograničenje
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 preko externalId: isti zahtjev dvaput vraća istu vožnju s replayed: 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 id događ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".