Errors

Every non-2xx response uses one envelope:

{
  "error": {
    "type": "validation_error",
    "code": "address_not_zimbabwean",
    "message": "We only deliver within Zimbabwe.",
    "details": [{ "field": "dropoff.address", "issue": "unserviceable" }],
    "request_id": "req_01JAV3K2QX8M4N7P"
  }
}

type is a small stable set you can branch on. code is specific. request_id is also returned in the X-Request-Id header: quote it to us.

type	HTTP	Meaning
authentication_error	401	Key, signature or timestamp problem
permission_error	403	Valid key, missing scope
not_found	404	Unknown resource, or one that is not yours
validation_error	422	Understood, contents rejected
conflict	409	Idempotency clash or illegal state change
rate_limit_error	429	Too many requests; see Retry-After
provider_error	502	Courier network rejected or unreachable
server_error	500	Our fault: send us the request_id

A delivery belonging to another client returns 404, never 403.

---