Errors

The Partner API uses standard HTTP status codes with JSON bodies. FastAPI-style validation errors return 422 Unprocessable Entity.

Common statuses

Code	Meaning	Action
`401`	Missing/invalid `X-API-Key` or `X-Client-ID`	Rotate credentials with Lynq ops
`403`	IP not on partner allowlist	Update allowlist or fix egress IP
`404`	Order or webhook not found	Check ULID and environment
`409`	Conflict (e.g. cancel not allowed)	Inspect current order status
`422`	Schema validation failed	Fix request payload
`503`	Quote routing/pricing unavailable	Retry with exponential backoff

Simple error:

{"detail": "Invalid API key"}

Structured detail (example):

{"detail": {"error": "distance_unavailable"}}

Validation (422):

{
  "detail": [
    {"loc": ["body", "dropoff", "contact_phone"], "msg": "field required", "type": "missing"}
  ]
}

Your listener should:

Return 2xx quickly after enqueueing work (avoid long DB transactions in the HTTP thread)
Return 4xx only for permanent misconfiguration Lynq should not retry (rare — consult Lynq if unsure)
Log X-Lynq-Signature, X-Lynq-Event, and envelope id for support tickets