Errors

Every refusal on both surfaces (/api/v1 and /api/compatible/v1) has the same JSON body:

{
  "error": "This vehicle is in Planning, not in Sell. Updates, re-pushes, prices, listings, deletion and sold-elsewhere apply once its sale window hands it to Sell.",
  "code": "PLANNING_STOCK"
}

Bulk endpoints never fail the whole batch for one bad item. They answer 200 with one result per item, and each failed item carries its own status, code (when it has one) and errors[]:

{
  "items": [
    { "vin": "1FTFW1ET5DFC10312", "status": 409, "code": "PLANNING_STOCK", "errors": ["This vehicle is in Planning, not in Sell. …"] },
    { "vin": "2FTFW1ET5DFC10313", "status": 201, "id": "clx…", "href": "/api/v1/vehicles/clx…" },
    { "vin": "3FTFW1ET5DFC10314", "status": 403, "code": "PLANNING_NOT_ENABLED", "errors": ["…"] }
  ],
  "created": 1, "updated": 0, "conflicts": 1, "invalid": 0, "refused": 1
}

refused counts the items that answered 403 — planning stock on an organization without Planning, an embedded listing without the listings scope, or a planning item without planning:write. It's additive: existing counters (created/updated/conflicts/invalid) are unchanged, on both POST /api/v1/vehicles/bulk and POST /api/compatible/v1/units/bulk.

Status codes

202 is not an error: it means the request was staged for Cypress review (sold-elsewhere, or a removal while a deal is in progress). The decision arrives later as a webhook — see De-listing.

Codes

Offers, listings, external ids and retries (1.5.0)

The offer and listing commands answer the same codes to every caller: an integration, a connected app or an agent. A decision that is refused writes nothing.

Planning codes (1.3.0)

From the Planning API. QUARTER_CLOSED is the one code added since (1.4.0):

QUARTER_PASSED and QUARTER_CLOSED are different codes: QUARTER_PASSED (422) is parking until a quarter that has already started; QUARTER_CLOSED (409) is acting on a quarter that is over.

Buy planning codes (1.4.0)

From the Planning API (Buy planning). QUARTER_CLOSED is the same code as above, here for the dealer's own plan (it carries no details), and BUY_PLANNING_NOT_ENABLED is in the table above. The approval of a quarter has its own three codes, and two more guard the removal of a target and of a purchase:

Another organization's target or purchase is 404, as one that does not exist. A body that doesn't validate is 422 with the same error and details as everywhere else.

Subscribing to the BUY.* webhooks (POST or PUT on /api/v1/webhooks/subscriptions) answers 403 SCOPE_MISSING when the key lacks buy-planning:read, 403 BUY_PLANNING_NOT_ENABLED when the organization has no Buy planning, and 422 when the subscription would use the MANHEIM names ("BUY.* events are available only on the Cypress dialect"). See Webhooks.

A bulk planning move (moves, moves/track, moves/park, moves/unpark) doesn't refuse a vehicle it can't move — it lists it in skipped with a reason, including an unknown id or another organization's (not in the plan), and moves the rest. It answers 409 only when every vehicle was skipped.

One exception: a closed quarter. A request that would change a vehicle in a window of a quarter that is over is refused whole with 409 QUARTER_CLOSED — nothing is applied, not even to the vehicles that could have changed — and details.vehicleIds lists exactly the vehicles it blocks, so you can send the request again without them:

{
  "error": "This quarter is closed. A closed quarter is history, so its plan no longer changes.",
  "code": "QUARTER_CLOSED",
  "details": { "vehicleIds": ["veh_a…", "veh_c…"], "quarter": "2026-Q3" }
}

details.quarter is present when those vehicles' windows all count in the same quarter. error is one fixed sentence: switch on code.

Changed in 1.4.0

API 1.4.0 added Buy planning over the API (new scopes, routes, codes and webhooks; the scope strings and everything that already existed are unchanged), and changed one thing for existing keys that this page is about: a request that changes a quarter that is over now answers 409 QUARTER_CLOSED. (The other change is a delivery, not an error: OFFERS.ACCEPTED is now also sent when a buyer accepts a counter. See Webhooks.) A move into a window of such a quarter, a move to OPERATION or a park of a vehicle scheduled in one, a track change of a planned vehicle in one, and the hand-off of one of its windows used to be accepted, except that a move into a window, or a hand-off, answered 409 WINDOW_CLOSED when the window itself had closed (which is now answered only for a window that has closed in a quarter still in progress). A hand-off preview of such a window answers QUARTER_CLOSED too, instead of a digest the confirm would refuse. A vehicle already in Sell can still change track, and blockers and demotions are not refused: see Closed quarters.

Before 1.1.0

Refusals carried only error (and details on 422). The code field and PLANNING_STOCK/LIFE_STAGE_READ_ONLY arrived in API 1.1.0; ORG_NOT_ACTIVE, PLANNING_NOT_ENABLED, SCOPE_MISSING and CHANNEL_NOT_GRANTED arrived in 1.2.0, alongside GET /api/v1/organization (see Your organization and key); the planning codes arrived in 1.3.0 with the Planning API, and QUARTER_CLOSED in 1.4.0.

Some older statuses changed. API 1.2.0 changed planning stock at an organization without Planning from 409 PLANNING_STOCK to 403 PLANNING_NOT_ENABLED, and changed a vehicles-only key pushing a vehicle/unit with an embedded listing/offering from creating it (with the listing silently dropped) to 403 SCOPE_MISSING. API 1.3.0 changed:

• A PATCH /api/v1/vehicles/{id} on planning stock, at an organization with Planning, from a key without planning:write, now answers 403 SCOPE_MISSING; 1.2.0 answered 409 PLANNING_STOCK. (A body naming prices, listing or images still answers 409 PLANNING_STOCK; without Planning it is still 403 PLANNING_NOT_ENABLED.)
• A POST /api/compatible/v1/units/bulk item whose embedded offering names an ungranted channel used to create the unit without the offering and answer 201; it now answers that item 422 CHANNEL_NOT_GRANTED and creates nothing.

API 1.3.0 also gives existing keys one new capability: GET/PUT /api/v1/vehicles/{id}/ownership needs only the vehicles scope for a vehicle in Sell, so a key with the default scopes can read and replace the purchase & financing record of its organization's Sell vehicles. And webhooks about planning stock — VEHICLES.* for a vehicle in Operation or Planning, and every PLAN.* event — reach only a Cypress-dialect subscription that lists them, so an unfiltered or MANHEIM subscription receives none of them (see Webhooks). Every other older status and message is unchanged.