Core concepts
Errors and retries
One envelope for every failure, with a stable machine-readable code next to a human message. The code is the part we promise not to change.
The envelope#
Every error — on every endpoint — has the same shape. There is no endpoint that returns a bare string, and none that returns 200 with a failure inside it.
{
"error": {
"code": "invalid_request",
"message": "Missing required fields: dropoff_lat, dropoff_lng",
"details": { "missing": ["dropoff_lat", "dropoff_lng"] }
},
"request_id": "b6d3f7c2-2f41-4f7e-9c1a-0a5d6e8b4c11"
}error.code— stable. Branch on this.error.message— for a human. It may be reworded to be clearer; never match on it.error.details— present when there is something specific to say, such as which fields were missing, or which status blocked a cancellation.request_id— on every response, success or failure. One identifier beats a screenshot in a support thread.
// Branch on the code. The message is written for a human reading a log,
// and we reserve the right to make it clearer.
switch (err.code) {
case "invalid_request": return fixAndSurface(err.details);
case "unprocessable": return offerAnotherOption(err.message);
case "company_inactive":
case "plan_required": return pageOps();
case "idempotency_conflict": return useANewKey();
case "rate_limited":
case "internal_error": return retryWithBackoff();
default: return surface(err.message);
}Every code#
| Code | HTTP | What it means | What to do |
|---|---|---|---|
missing_api_key | 401 | No Authorization header. | Send the bearer token. Not retryable. |
invalid_api_key | 401 | Malformed, unknown or revoked key. | Check the key and its environment. Not retryable. |
company_inactive | 403 | The company is unapproved, suspended, or has bookings switched off. | A human at the dispatch company has to act. Stop retrying. |
plan_required | 402 | A live key, but the company is not on the Dispatch Pro plan (never was, or it lapsed). Test keys are unaffected. | The company owner upgrades from Subscription in the dashboard. Stop retrying. |
invalid_request | 400 | Missing or malformed input — a required field, a non-numeric coordinate, a bad cursor. | Read details, fix the request. Not retryable as sent. |
unprocessable | 422 | Well-formed, but cannot be done: outside Nigeria, COD not enabled, no payout account, delivery too far along to cancel. | Change the plan, not the syntax. Show the message to whoever can act on it. |
not_found | 404 | No delivery with that id or tracking code — in this environment, for this company. | Check the environment of your key before assuming it is gone. |
test_limit_reached | 429 | A test key has made 50 bookings in the last 24 hours. Test mode is for building, not running deliveries. | Wait, or use a live key (Dispatch Pro) for real traffic. |
quota_exceeded | 402 | This month's API booking allowance is spent. | Wait for the reset in details.resets_at, or contact support for a higher limit. Not retryable before then. |
idempotency_conflict | 409 | This Idempotency-Key was already used for a different booking. | Use a new key. See Idempotency. |
rate_limited | 429 | Too many requests for this operation. | Wait for Retry-After seconds, then retry. Safe to retry. |
internal_error | 500 | Our fault. | Retry with backoff. If it persists, send us the request_id. |
HTTP status codes#
| Status | When |
|---|---|
| 200 | A successful read, cancel, or replayed booking. |
| 201 | A delivery was created — or an idempotent replay of one. |
| 400 | Malformed request. |
| 401 | Authentication failed. |
| 403 | Authenticated, but the company cannot take this action. |
| 404 | No such delivery in this environment. |
| 402 | This month's API booking allowance is spent. |
| 409 | Idempotency key reused for a different request. |
| 422 | Understood, refused on the merits. |
| 429 | Rate limited. |
| 500 | Unhandled failure on our side. |
Rate limits#
Limits are per company and per environment, counted over a sliding minute. Your test key cannot throttle your live traffic, and minting more keys does not buy more quota — a company may hold five keys per environment, and they share one budget.
| Operation | Limit |
|---|---|
Reads — GET a delivery, list deliveries | 240 / minute |
Quotes — GET /quote | 120 / minute |
| Bookings and cancellations | 60 / minute |
Payment links — POST /deliveries/{id}/pay | 20 / minute |
These are set well above what a busy dispatch company does and well below what a runaway retry loop does — the failure they exist to catch is a deploy that books the same delivery forever, which costs real riders before anybody notices. If you have a legitimate reason to exceed them, ask rather than working around them.
HTTP/1.1 429 Too Many Requests
Retry-After: 23
{
"error": {
"code": "rate_limited",
"message": "Too many requests. The limit for this operation is 60 per minute; retry in 23s.",
"details": { "retry_after_seconds": 23, "limit_per_minute": 60 }
},
"request_id": "…"
}Read Retry-After and wait that many seconds. It is also in the body as error.details.retry_after_seconds, alongside the limit you hit.
Monthly booking allowance#
Bookings — and only bookings — are metered per calendar month, UTC. Quotes, reads, cancellations and payment links are not counted, and neither are test-mode bookings.
| Plan | Live API bookings per month |
|---|---|
| Free | None: live keys need Pro (402 plan_required) |
| Pro | 10,000 |
| Test mode | Unlimited, on either plan |
Every successful booking response carries the allowance as headers, so you can watch it drain rather than discover the limit by hitting it:
X-Api-Quota-Limit: 50
X-Api-Quota-Remaining: 38
X-Api-Quota-Reset: 2026-10-01T00:00:00.000ZWhen it runs out, bookings are refused with 402 quota_exceeded until the first of the next month. Nothing else is affected — your booking link, your dashboard and your existing deliveries carry on exactly as before.
{
"error": {
"code": "quota_exceeded",
"message": "Your plan includes 10000 API bookings a month and you have used them all. The allowance resets on 2026-10-01.",
"details": { "limit": 10000, "used": 10000, "resets_at": "2026-10-01T00:00:00.000Z" }
},
"request_id": "…"
}The platform fee is separate
Retrying safely#
Two rules carry almost all of the weight:
- Retry only what is safe to retry. Timeouts, dropped connections,
5xxand429. A4xxmeans the request is wrong; sending it again does not make it right. - Never retry a booking without an
Idempotency-Key. A timeout tells you nothing about whether the delivery was created. With a key, the retry is free; without one, it is a second rider.
async function withRetry(call, { attempts = 4 } = {}) {
for (let i = 0; ; i++) {
try {
return await call();
} catch (err) {
const retryable = err.status >= 500 || err.status === 429 || err.timeout;
if (!retryable || i >= attempts - 1) throw err;
// Exponential, with jitter — a fleet retrying in lockstep is a stampede.
await sleep(2 ** i * 1000 + Math.random() * 250);
}
}
}Timeouts
Quotes and reads are fast — a 10–20 second timeout is generous. A booking does more work (pricing, insert, assignment kick-off), so allow 30 seconds before giving up, and treat the timeout as "unknown", not "failed": retry with the same key, or read the delivery back.
Getting help#
Email [email protected] with the request_id, the environment, and roughly when it happened. That is enough to find the exact call — far more than a description of what you expected.
Nothing sensitive comes back in an error