Errors and FAQs

Every Studio Promote error comes back with "success": false and a code. Decide what to do from code; message is written for people and can change.

{
  "success": false,
  "statusCode": 400,
  "code": "VEHICLE_NOT_FOUND",
  "message": "1 vehicle(s) could not be found in inventory",
  "data": { "notFound": ["NOT-A-VIN"] }
}

Error codes

Code	Status	What happened	What to do
`INVALID_REQUEST`	`400`	Something in the request is wrong. `details.errors` lists every problem at once.	Fix each one and send again.
`UNAUTHORIZED`	`401`	The API key is missing or wrong.	Send `Authorization: Bearer YOUR_API_KEY`. If a key that works gets this once, retry.
`TEAM_NOT_RESOLVED`	`400`	The key isn't linked to a rooftop.	Generate a key for the rooftop in Developer Hub.
`VEHICLE_NOT_FOUND`	`400`	A vehicle isn't in this rooftop's inventory, or an entry has no usable identifier. `data.notFound` lists which.	Check the VIN or stock number.
`VEHICLE_AMBIGUOUS`	`400`	One value matches two different vehicles. `data.ambiguous` shows them.	Send the VIN instead.
`VEHICLE_IN_OTHER_PROMOTION`	`409`	A vehicle is already in another hand-picked promotion. `data.conflicts` names it.	Complete or delete that promotion, or leave the vehicle out.
`ASSET_NOT_FOUND`	`400`	An image id can't be used, or a link matches an image that was deleted.	Pick an id from List images, or change the link (for example, add `?v=2`).
`INVALID_ASSET_URL`	`400`	An image link is malformed, private or internal, doesn't resolve, or didn't answer within 30 seconds.	Use a public link to a PNG or JPG.
`PROMOTION_NOT_FOUND`	`404`	There's no such promotion for this rooftop.	Check the id.
`INVALID_STATUS_CHANGE`	`409`	That action, or a delete, isn't allowed in the current status.	See the table in Change status.
`VALIDATION_FAILED`	`400`	Spyne refused the request; `details` or `message` explains why.	Fix what it describes.
`RATE_LIMITED`	`429`	Too many calls this minute.	Wait the seconds in the `Retry-After` header, then retry.
`SERVICE_UNAVAILABLE`	`502` or `503`	A Spyne service is briefly unavailable.	Wait a moment and retry.

An unexpected server error can also return a bare 500 with no body. Retry it like SERVICE_UNAVAILABLE.

Rate limits

Calls	Limit per rooftop
Changes: create (including dry runs), change status, delete, add an image	30 a minute
Reads: list and retrieve promotions, list images	120 a minute

The limit is shared by everyone using the rooftop and resets at the start of each clock minute (:00). Invalid requests count too.

Common questions

Can I change a promotion after creating it? Not yet: there's no edit call. Complete or delete it, then create a new one with your changes.

Why don't the photos change straight away? They're updated in the background over the next few minutes. Retrieve the promotion to see its status.

What's the difference between pause and complete? Pause stops the promotion and lets you resume it with activate. Complete ends it for good and can't be undone.

Can a vehicle be in two promotions? A vehicle shows one promotion at a time, and priority decides which. A vehicle already in another hand-picked promotion is refused with 409: complete or delete that promotion first. Moving it across automatically (allowReassignment) isn't supported yet.

Why did I get 429 after only a few calls? Calls made earlier in the same clock minute count, including other people's calls for the same rooftop. Wait the seconds in Retry-After.

Why does Transform a vehicle refuse my banner? While the rooftop has a promotion that is active, scheduled or paused, a Transform a vehicle request carrying its own mediaKitConfig.banner or billboard is refused, because the promotion would override it. Complete the promotion first; pausing isn't enough.

Can I delete an image I uploaded? Not through this API. Reuse it in other promotions with its assetId.

How do I test safely? Use dry runs while you build. Create test promotions as drafts ("draft": true), then delete them when you're done.