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
{
  "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.
handling
// 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#

CodeHTTPWhat it meansWhat to do
missing_api_key401No Authorization header.Send the bearer token. Not retryable.
invalid_api_key401Malformed, unknown or revoked key.Check the key and its environment. Not retryable.
company_inactive403The company is unapproved, suspended, or has bookings switched off.A human at the dispatch company has to act. Stop retrying.
plan_required402A 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_request400Missing or malformed input — a required field, a non-numeric coordinate, a bad cursor.Read details, fix the request. Not retryable as sent.
unprocessable422Well-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_found404No 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_reached429A 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_exceeded402This 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_conflict409This Idempotency-Key was already used for a different booking.Use a new key. See Idempotency.
rate_limited429Too many requests for this operation.Wait for Retry-After seconds, then retry. Safe to retry.
internal_error500Our fault.Retry with backoff. If it persists, send us the request_id.

HTTP status codes#

StatusWhen
200A successful read, cancel, or replayed booking.
201A delivery was created — or an idempotent replay of one.
400Malformed request.
401Authentication failed.
403Authenticated, but the company cannot take this action.
404No such delivery in this environment.
402This month's API booking allowance is spent.
409Idempotency key reused for a different request.
422Understood, refused on the merits.
429Rate limited.
500Unhandled 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.

OperationLimit
Reads — GET a delivery, list deliveries240 / minute
Quotes — GET /quote120 / minute
Bookings and cancellations60 / minute
Payment links — POST /deliveries/{id}/pay20 / 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.

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

PlanLive API bookings per month
FreeNone: live keys need Pro (402 plan_required)
Pro10,000
Test modeUnlimited, 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:

on every booking
X-Api-Quota-Limit: 50
X-Api-Quota-Remaining: 38
X-Api-Quota-Reset: 2026-10-01T00:00:00.000Z

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

402
{
  "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

The allowance is about software, not deliveries. The platform fee applies to every booking on either plan, through the API or otherwise — see the split.

Retrying safely#

Two rules carry almost all of the weight:

  • Retry only what is safe to retry. Timeouts, dropped connections, 5xx and 429. A 4xx means 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.
backoff
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

Error messages never contain another company's data, and authentication failures deliberately do not distinguish an unknown key from a revoked one.