Errors

Every error uses the flat platform envelope:

{
  "error": {
    "code": "not_found",
    "message": "Resource not found",
    "details": null
  },
  "meta": {
    "request_id": "req_abc123",
    "environment": "production",
    "billing_units": 0
  }
}

Include meta.request_id when contacting support.

Codes you will encounter

HTTP	Code	Cause
400	`bad_request`	Malformed JSON, invalid payload (details carry the field errors), unknown `claim_status` filter, or unknown supplier reference.
401	`api_key_missing` / `api_key_invalid`	No bearer token, wrong prefix, or unknown/failed-hash key.
401	`api_key_revoked` / `api_key_expired`	The key was rotated/revoked or passed its expiry.
402	`account_suspended`	Your organization is suspended — contact support.
403	`scope_required`	The key lacks the scope named in `details.required`.
404	`not_found`	Unknown supplier/trip, or a trip that exists but is not linked to your organization.
409	—	Duplicate supplier `external_id`, or re-issuing a claim token for an already-claimed trip.
429	`rate_limited`	Monthly plan quota exhausted; check the `X-RateLimit-*` headers.
500	`internal_error`	Unexpected server error — safe to retry with backoff.

Idempotency notes

Starting a trip is not idempotent — use your external_ref plus GET /v1/partner/trips?external_ref=... to detect a duplicate before retrying a timed-out create.
PATCH is last-write-wins on the fields you send; unsent fields are untouched.