Driveosplatform catalogue

What the error messages mean

What each message means, which status comes with it and what is safe to retry.

When a program sends something that makes no sense, the answer has to say what went wrong. Here is the list of the most common answers, explained so you can see what caused them and what is safe to retry.

jsonoblik greške
{
  "statusCode": 400,
  "message": "Ovaj modul nije uključen za tvrtku.",
  "key": "errors.moduleDisabled",
  "locale": "hr"
}
  • statusCode — the HTTP status; it decides whether to retry.
  • message — a sentence for humans, in the request language (Accept-Language).
  • key — a stable machine code; it is never changed and never translated. Logic is based on it.
  • locale — the language the message is written in.

HTTP statuses

StatusMeansRetry?
200Success—
201Created (ride, key, cancellation)—
400The request is not valid: field, date, module, company stateno, fix the request
401The key is not recognised or the session expiredno, check the key
403Recognised but not allowed: scope, address, inactive companyno
404No such record in your companyno
409The state changed (the ride is already finished)no, fetch the state
429Rate limit exceededyes, after Retry-After
5xxAn error on our sideyes, with linear backoff
Why 404 and not 403A request for another company’s ride returns 404. A 403 response would say the record exists — that is information about another company that must not leak.

The codes that matter most

CodeStatusMeansFix
errors.invalidApiKey401The key is not recognisedCheck the header and the key
errors.apiKeyRevoked403The key was revokedIssue a new key
errors.apiKeyExpired403The key expiredIssue a new key with a new expiry
errors.apiKeyIpNotAllowed403The address is not on the listAdd the address or use another source
errors.forbidden403A scope is missingAdd the scope to the key
errors.moduleDisabled400The module is not enabled for the companyEnable addon.api_access
errors.tenantInactive403The company is not activeCheck the company subscription
errors.launchNotReady400The company is not ready to operateComplete the 12 readiness checks
errors.apiRideNeedsRoute400Not enough data for a routeSend both coordinates
errors.externalIdInvalid400Invalid external idLetters, digits and ._:- are allowed
errors.invalidPhone400Invalid phoneSend + and 6–30 characters
errors.tooManyStops400Too many intermediate stopsAt most 16
errors.rideTransitionNotAllowed409The state transition is not allowedFetch the current state
errors.invalidDate400The date is not YYYY-MM-DDFix the format
errors.invalidDateRange400from is after toSwap the bounds
errors.statsRangeTooLong400The range is longer than 92 daysSplit into two calls
errors.tooManyRequests429Rate limit exceededWait Retry-After seconds
errors.webhookEventsRequired400A webhook without eventsPick at least one event
errors.webhookEventUnknown400Unknown eventUse one of the four names

This is a selection: the code contains 739 distinct error keys. They all follow the same naming rule errors.<shortName>, so an unknown key can safely be shown to a user with a generic message.

Rate limits

ChannelLimitKey
Partner API /v1120 requests per minute per keyAPI key
Other requests120 per 60 seconds per sourceaddress and session
Sign-instricter, per address and accountaddress + account

A 429 response carries a Retry-After header in seconds. The recommended pattern is linear backoff with a small random jitter; retrying without waiting only extends the block.

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;
}

Idempotency and retries

  • Booking (POST /v1/rides) is idempotent via externalId: the same request twice returns the same ride with replayed: true.
  • Cancellation is idempotent by nature: cancelling a finished ride again returns 409, which is an expected state, not a failure.
  • Reads (GET) may be repeated freely; the only consequence is consumed rate limit.
  • Webhooks arrive at least once: deduplicate by event id.

Error language

The Accept-Language header selects the language of the message field (hr, en, sl, de). key never changes — logic is built on it. If the language is unavailable the response is in Croatian with locale: "hr".