Idempotency and retries - Lanesurf Agent API

Networks fail. When a call times out you don’t know whether it worked, so Lanesurf makes every write safe to send again. Posting a load needs an Idempotency-Key; the other writes are safe to repeat on their own.

Post a load: `Idempotency-Key` (required)

POST /v1/loads must carry an Idempotency-Key header (over MCP: the idempotency_key argument of post_load).

Make a new UUID for each load, and keep it until you know the load was created.
On a retry of the same load, send the same key and the same body.
Up to 200 characters. Keys are scoped to your API key.

You send	You get	A load is created?
No key	`400 idempotency_key_required`	No
A new key	`201` with the new load	Yes
The same key again, same load	`200` with the original load and its current status	No, it’s the same load
The same key while the first post is still running	`409 idempotency_in_progress` with `Retry-After: 5`	No. Wait 5 seconds and retry with the same key
The same key for a different load	`422 idempotency_key_reused`	No. Use a new key for a new load

A load that is missing fields (422 missing_fields) or that Lanesurf can’t process (400 load_rejected) is never created. Fix it and send it again: after missing_fields, reuse the same key; after load_rejected, check the stops and dates with the person and use a new key.

Post a truck: optional `Idempotency-Key`

POST /v1/carrier/trucks takes an optional Idempotency-Key (MCP: post_truck’s idempotency_key), up to 200 characters. Posting again with the same key from the same API key returns the existing truck, with the same truck_id, instead of a duplicate (the answer is 201 either way). Without a key, every post is a new truck.

Writes that are safe to repeat as they are

Call	Sending it again
Accept an offer	Same offer, same answer. `409 offer_changed` if the carrier changed its rate since; ask the person again
Mark a load covered	Same answer
Bid on a load	Updates your bid on that load (latest terms win): `200` with `action: updated` or `unchanged`. One bid per carrier per load, never a duplicate. After the broker accepts it: `409 bid_decided`. A bid can be changed up to 5 times (`409 bid_update_limit`)
Finish an `incomplete` bid	Send the bid again. Within 2 minutes, from the same key: the original rate, truck and note are used. After that, from any of your carrier’s keys: the new request’s terms are used
Save a lane	The same lane (same states, cities and equipment, any letter case) returns the lane already saved
Remove a truck or lane	A second remove answers `404 not_found`; the item is already gone
Decline an offer	Records the same choice. `409 already_covered` once the load is covered

Reads (GET) are always safe to repeat.

When to retry

Answer	Retry?	How
Timeout or connection error	Yes	The same request; for `POST /v1/loads`, the same `Idempotency-Key`
`429 rate_limited`	Yes	After `Retry-After` seconds. See Rate limits
`409 idempotency_in_progress`	Yes	After 5 seconds, same key and load
`409 already_bid`	Yes	In a few seconds; another key of your carrier is bidding on this load right now
`500 internal`, `502 upstream_error`	Yes, a few times	Wait, then back off: for example 2, 4, 8, 16 seconds, then stop and tell the person
`503 unavailable`	Yes, later	Wait `Retry-After` when it’s set. If the key couldn’t be checked, the key may be fine: don’t ask for a new one
Any other `4xx`	No	Fix the request first. Sending it unchanged gives the same answer

When a call keeps failing, quote its request_id to support@lanesurf.com. You can also send your own X-Request-Id and keep it with your retries. See Request IDs.

​Post a load: Idempotency-Key (required)

​Post a truck: optional Idempotency-Key

​Writes that are safe to repeat as they are

​When to retry

Post a load: `Idempotency-Key` (required)

Post a truck: optional `Idempotency-Key`

Writes that are safe to repeat as they are

When to retry