Errors - Lanesurf Agent API

Errors are JSON with a message and a stable code:

{ "error": "invalid API key", "code": "invalid_api_key", "request_id": "req_0192f3a4-7b1c-7d2e-9f00-1a2b3c4d5e6f" }

error: a message for people. It can change.
code: always present. Branch on code, not on error.
request_id: this request’s id. See Request IDs.
422 missing_fields also has missing, the exact fields still needed.
409 offer_changed also has current_rate, the offer’s rate now.
Signup errors, broker load errors and many others also have next_step: what the agent should do next.
Over MCP, a failed tool returns this same JSON as an error result, plus retry_after_seconds when you should wait before retrying.

The error body is described by the Error schema in /openapi.yaml. For when to retry, see Idempotency and retries; for limits, Rate limits.

Error codes

`code`	HTTP	Meaning	What to do
`missing_api_key`	`401`	No `Authorization` header	Send `Authorization: Bearer ls_live_…`
`invalid_api_key`	`401`	The key is wrong, malformed or revoked	Check the key. Don’t retry unchanged
`wrong_role`	`403`	A carrier key on a broker route, or a broker key on a carrier route	Use the right key
`verification_required`	`403`	The carrier account is under review (`needs_review`): only verified carriers can search loads, read a load, get truck matches, list outreach or bid	Tell the person their carrier account is under review. Trucks, lanes and the bid list still work
`invalid_request`	`400`	The body isn’t valid JSON for the route, or a value is wrong (at signup, e.g. “use your work email”; accept without a `rate`; a `limit` that isn’t a whole number from 1 to 100). The message says which	Fix it. Don’t retry unchanged
`idempotency_key_required`	`400`	Broker: `POST /v1/loads` came without an `Idempotency-Key` (MCP: `post_load` without `idempotency_key`). Nothing was created. Missing fields are reported first	Send a new UUID as the key. Keep it, and reuse it if you retry this load
`load_rejected`	`400`	Broker: Lanesurf couldn’t process the load (bad stop cities, states, zip codes or dates)	Don’t retry it unchanged. Check the stops and dates with the person, then send it with a new `Idempotency-Key`
`missing_fields`	`422`	A load, truck, lane or signup lacks required fields (see `missing`). A broker’s verify reports this before a code attempt is used	Ask the person for exactly those, then send it again
`invalid_code`	`422`	Signup: wrong code. The message says how many attempts are left	Ask for the code again
`idempotency_key_reused`	`422`	This API key already used this `Idempotency-Key` for a different load (broker) or a different truck (carrier). Nothing was created	Use a new key for the new load or truck
`not_found`	`404`	No such load, offer, truck, lane or signup for this key	Check the id
`offer_changed`	`409`	Broker: the carrier changed its rate since the person agreed to it. Nothing was accepted. `current_rate` has the new rate	Tell the person the new rate and ask again. If they agree, accept again with that `rate`
`invalid_state`	`409`	Broker: the load’s state doesn’t allow the change: deleted, covered (reopen it first), paused (resume it before changing stops), or its first pickup has passed	Tell the person `error`; follow `next_step`
`already_covered`	`409`	Broker: another offer was already accepted, the load was marked covered, or it was deleted. A load can’t be both accepted and marked covered	Read the load again; tell the person
`idempotency_in_progress`	`409`	Broker: a post with this `Idempotency-Key` from this API key is still being processed	Wait `Retry-After` seconds (5), then retry with the same key and load
`already_bid`	`409`	Carrier: another key of your carrier is placing a bid on this load right now	Try again in a few seconds; it then updates that bid
`bid_decided`	`409`	Carrier: the broker already accepted your bid on this load, so it can’t change	Tell the person. (A declined bid can be sent again with a new rate.)
`bid_update_limit`	`409`	Carrier: this bid was already changed the most times allowed (5). It stands as it is	Don’t bid again on this load
`broker_name_taken`	`409`	Broker signup: a brokerage with this `company_name` is already set up with Lanesurf	Ask Lanesurf for a key, or verify again with the corrected `company_name`
`broker_name_mismatch`	`409`	Broker signup: this signup already created the brokerage under another name	Verify again with the `company_name` you sent first
`existing_customer`	`409`	Broker signup: the company already uses Lanesurf	Don’t sign up and don’t retry. Their Lanesurf admin or account manager gives them access
`already_redeemed`	`409`	Signup: this signup was already completed and its API key is in use (for example, a verify sent again after the key was used)	Tell the person. A carrier who lost the key can start signup again; a brokerage contacts support@lanesurf.com with the `request_id`
`signup_expired`	`410`	Signup: the code expired (10 minutes) or ran out of attempts (5)	Start signup again
`rate_limited`	`429`	Too many requests: signup limits, over 120 requests per minute from one API key (counted per Lanesurf server), or too many wrong API keys from one network	Wait `Retry-After` seconds, then retry
`internal`	`500`	Unexpected error	Retry later
`upstream_error`	`502`	A Lanesurf system behind the API failed	Retry later
`unavailable`	`503`	Lanesurf couldn’t check the API key right now (the key itself may be fine), or signup, carrier or setup routes can’t run (code sending or a Lanesurf system is down, or the feature is off)	Retry later; wait `Retry-After` when set. Don’t ask for a new key

By HTTP status

HTTP	Codes
`400`	`invalid_request`, `idempotency_key_required`, `load_rejected`
`401`	`missing_api_key`, `invalid_api_key`
`403`	`wrong_role`, `verification_required`
`404`	`not_found`
`409`	`already_covered`, `invalid_state`, `offer_changed`, `already_bid`, `bid_decided`, `bid_update_limit`, `idempotency_in_progress`, `broker_name_taken`, `broker_name_mismatch`, `existing_customer`, `already_redeemed`
`410`	`signup_expired`
`422`	`missing_fields`, `invalid_code`, `idempotency_key_reused`
`429`	`rate_limited`
`500`	`internal`
`502`	`upstream_error`
`503`	`unavailable`

Request IDs

Every response has an X-Request-Id header, and every error body has the same id as request_id. Over MCP, a tool error’s JSON has request_id and a successful result has it in _meta["lanesurf/request_id"]. You can send your own X-Request-Id (8 to 64 letters, digits, ., _ or -) and Lanesurf uses it. Otherwise Lanesurf makes one (req_…). When something keeps failing, quote the request_id to support@lanesurf.com.

Rate limits

Over a limit you get 429 rate_limited with a Retry-After header in seconds. Wait that long, then retry. Every limit is on Rate limits. Request bodies are capped at 1 MB.

For what each load, truck and bid status means, see Statuses.

​Error codes

​By HTTP status

​Request IDs

​Rate limits

Error codes

By HTTP status

Request IDs

Rate limits