Errors and retries

Errors use one JSON shape:

{
  "error": {
    "code": "invalid_request",
    "message": "request body failed validation",
    "request_id": "6ee0f7d4532d4632bb01a27b328bece9"
  }
}

The same request ID is returned in the X-Request-ID header. Record it when investigating a failed request; do not infer handling from the human-readable message alone.

Status handling

HTTP status	Handling
401 or 403	Correct the credential or its operation scope before retrying.
411	Send a request with Content-Length; standard HTTP clients and curl --data-binary do this automatically.
413	Reduce the operating snapshot to the configured request-size limit.
422	Correct the request or trial-limit violation before retrying it unchanged.
429	Retry only after Retry-After when present. Without that header, the trial allowance may be exhausted rather than temporarily rate-limited.
500, 502, or 503	Retry with bounded exponential backoff. Retain the request ID if the failure persists.
504	The end-to-end planning deadline expired. Retry once, then reduce the planning problem or request a larger solve allowance.

Manifest and booking-check requests are stateless and do not modify source-platform data, so transport retries do not duplicate bookings or manifests. A repeated bounded solve may return a different valid plan as road data, queue time, or optimizer search changes.

Result statuses are not HTTP errors

A successful booking check returns HTTP 200 with feasible, infeasible_proven, or unknown. In particular, unknown means the bounded check reached neither a valid plan nor a proof of impossibility. It must not be converted into an automatic rejection.