Launching soon. Check your price now and join the list to be first when bookings open. Check your price

Sendway

Errors & limits

Every failure comes back in the same shape, with a code that is safe to branch on.

The envelope

json
{
  "error": {
    "type": "invalid_request",
    "code": "unknown_town",
    "message": "That town is not one of our pickup towns. List them with GET /v1/towns.",
    "param": "dest_town_id",
    "request_id": "req_97515958f3975668c37281f2"
  }
}

Branch on code, never on message — messages are written for people and we improve their wording. param names the offending field, which is what you highlight in a form.

Log request_id. Every response carries one in the X-Request-Id header too, and quoting it turns a support conversation into a single lookup.

Types

TypeHTTPDo
authentication_error401Fix the key. Do not retry.
permission_error403Key lacks a scope, or the account is not approved.
invalid_request400 / 409 / 422Fix the request. Do not retry unchanged.
not_found404Wrong id, or it belongs to another account.
rate_limit_error429Back off and retry.
api_error500Ours. Retry with backoff.

Codes worth handling

CodeMeans
insufficient_scopeThe key may not do this. Names the missing scope.
client_not_activeLive key, unapproved account. Test keys still work.
unknown_townNot a pickup town. Refresh your cached list.
quote_not_neededThis parcel has an online price. Book it with POST /v1/parcels.
quote_request_not_openThe quote request is not waiting to be accepted: still pending, already accepted, expired or cancelled.
quote_request_not_foundWrong id, or it belongs to another account.
missing_sender_phoneSend sender_phone, or add a phone number to your SendWay account.
outside_kenyaThe address resolves outside Kenya. SendWay only delivers within Kenya.
missing_destinationSend a town id or destination coordinates.
not_quotableRoute outside the network. Fall back to your own shipping.
quote_requiredWe price this parcel by hand (large sofas, beds, values over KES 300,000, very large bulk loads). Send a quote request.
category_not_availableLarge items and bulk loads only go to pickup towns for now.
invalid_categoryMissing or unknown large_item, empty bulk_lines, or no declared_value for a fragile parcel or large item.
missing_package_sizeStandard and fragile parcels need a package_size.
parcel_not_cancellableAlready moving. Contact support.
run_already_scannedYour batch is locked for payment; the parcel is committed.
rate_limitedToo many requests this minute.

Rate limits

The default is 120 requests per minute per account, across all your keys. Every response tells you where you stand:

RateLimit-Policy: 120;w=60
RateLimit: limit=120, remaining=111, reset=22

Over the limit you get 429. Back off rather than retrying immediately — and if you are hitting it legitimately, ask and we will raise it rather than having you engineer around it.

Caching towns and quotes is the cheapest way to stay well under.

Retrying safely

Reads are safe to retry. The one write that needs care is booking a parcel — always send X-Idempotency-Key so a retry replays the first result instead of creating a second parcel. See parcels.

Still stuck?

Email info@shopinn.co.ke with the request_id and roughly when it happened.