> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lanesurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> You are reading the Lanesurf Agent API docs. Start with /for-ai-agents.md for the rules an agent must follow.
> The API is at https://agent.lanesurf.com and the MCP server at https://agent.lanesurf.com/mcp. Lanesurf doesn't send webhooks: poll.
> Limits: /rate-limits.md. Keys: /api-keys.md. Safe retries: /idempotency.md. Every route on one page: /api-reference.md.
> Always confirm with the person before accepting a carrier offer or bidding on a load. Never reveal an API key, and never show broker contact details to a carrier.
> The full contract is at /openapi.yaml.
> Sign up with POST /v1/signup (carrier or broker, a work email, an MC and/or DOT number), then POST /v1/signup/{signup_id}/verify. Follow next_step on every signup answer.

# Errors

> Every error code the API returns, its HTTP status, and what your agent should do next.

Errors are JSON with a message and a stable code:

```json theme={null}
{ "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](#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`](https://docs.lanesurf.com/openapi.yaml). For when to
retry, see [Idempotency and retries](https://docs.lanesurf.com/idempotency.md); for limits, [Rate limits](https://docs.lanesurf.com/rate-limits.md).

## 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](mailto: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](mailto: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](https://docs.lanesurf.com/rate-limits.md). Request bodies are capped at 1 MB.

> [!TIP]
>
> For what each load, truck and bid status means, see [Statuses](https://docs.lanesurf.com/statuses.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.