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.
{
"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 themessageis written in.
HTTP statuses
| Status | Means | Retry? |
|---|---|---|
| 200 | Success | — |
| 201 | Created (ride, key, cancellation) | — |
| 400 | The request is not valid: field, date, module, company state | no, fix the request |
| 401 | The key is not recognised or the session expired | no, check the key |
| 403 | Recognised but not allowed: scope, address, inactive company | no |
| 404 | No such record in your company | no |
| 409 | The state changed (the ride is already finished) | no, fetch the state |
| 429 | Rate limit exceeded | yes, after Retry-After |
| 5xx | An error on our side | yes, with linear backoff |
404. A 403 response would say the record exists — that is information about another company that must not leak.The codes that matter most
| Code | Status | Means | Fix |
|---|---|---|---|
errors.invalidApiKey | 401 | The key is not recognised | Check the header and the key |
errors.apiKeyRevoked | 403 | The key was revoked | Issue a new key |
errors.apiKeyExpired | 403 | The key expired | Issue a new key with a new expiry |
errors.apiKeyIpNotAllowed | 403 | The address is not on the list | Add the address or use another source |
errors.forbidden | 403 | A scope is missing | Add the scope to the key |
errors.moduleDisabled | 400 | The module is not enabled for the company | Enable addon.api_access |
errors.tenantInactive | 403 | The company is not active | Check the company subscription |
errors.launchNotReady | 400 | The company is not ready to operate | Complete the 12 readiness checks |
errors.apiRideNeedsRoute | 400 | Not enough data for a route | Send both coordinates |
errors.externalIdInvalid | 400 | Invalid external id | Letters, digits and ._:- are allowed |
errors.invalidPhone | 400 | Invalid phone | Send + and 6–30 characters |
errors.tooManyStops | 400 | Too many intermediate stops | At most 16 |
errors.rideTransitionNotAllowed | 409 | The state transition is not allowed | Fetch the current state |
errors.invalidDate | 400 | The date is not YYYY-MM-DD | Fix the format |
errors.invalidDateRange | 400 | from is after to | Swap the bounds |
errors.statsRangeTooLong | 400 | The range is longer than 92 days | Split into two calls |
errors.tooManyRequests | 429 | Rate limit exceeded | Wait Retry-After seconds |
errors.webhookEventsRequired | 400 | A webhook without events | Pick at least one event |
errors.webhookEventUnknown | 400 | Unknown event | Use 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
| Channel | Limit | Key |
|---|---|---|
Partner API /v1 | 120 requests per minute per key | API key |
| Other requests | 120 per 60 seconds per source | address and session |
| Sign-in | stricter, per address and account | address + 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.
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 viaexternalId: the same request twice returns the same ride withreplayed: 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".