Errors and FAQs

Errors from POST /api/pv1/instant come back with "success": false, a code to branch on and a plain-English message. Decide what to do from code; message can change.

{
  "success": false,
  "statusCode": 400,
  "code": "INVALID_REQUEST",
  "message": "exteriorColor is required: this VIN isn't in the rooftop's inventory with an exterior color; condition is required: this VIN isn't in the rooftop's inventory with a condition (new or used)",
  "details": {
    "errors": [
      "exteriorColor is required: this VIN isn't in the rooftop's inventory with an exterior color",
      "condition is required: this VIN isn't in the rooftop's inventory with a condition (new or used)"
    ]
  }
}

Error codes

Code	Status	What happened	What to do
`INVALID_REQUEST`	`400`	A field is missing or invalid. Each problem is listed in `details.errors`.	Fix the listed fields and send again.
`INVALID_REQUEST`	`400`	"stockNumber is already used by another vehicle at this rooftop".	Send this vehicle's own stock number, or leave `stockNumber` out.
`UNAUTHORIZED`	`401`	The key is missing, wrong or expired.	Send `Authorization: Bearer YOUR_API_KEY` with a valid key.
`INSTANT_NOT_ENABLED`	`403`	Studio Instant is off for this rooftop and vehicle condition (new or used).	Ask the dealer or Spyne to switch it on; until then, plan a photo shoot.
`API_KEY_CANNOT_GENERATE`	`403`	The key isn't linked to a Spyne user, so it can check but not generate.	Use a key created in Spyne Console.
`ROOFTOP_NOT_FOUND`	`404`	`rooftopId` isn't a rooftop this key can use.	Leave `rooftopId` out with a rooftop key, or send one of your group's rooftops.
`VEHICLE_HAS_PHOTOS`	`409`	The vehicle already has its own processed photos (or the dealer declined Instant for it).	Nothing to do: read its images with Read status and images.
`VEHICLE_IN_OTHER_ROOFTOP`	`409`	The VIN belongs to another rooftop's inventory.	Send it with that rooftop's key, or check the VIN.
`RATE_LIMITED`	`429`	More than 120 requests in a minute.	Wait the seconds in the `Retry-After` header, then retry.
`SERVICE_UNAVAILABLE`	`503`	A Spyne service was briefly unavailable, or a generate for this VIN is already running.	Retry after a short wait; a repeat generate is safe.

Retry 429 after Retry-After, and 503 after a short wait with back-off. Don't retry 400, 401, 403 or 404 unchanged: fix the request first.

Read status and images has its own answers: 404 { "message": "Dealer vin not found" } for a VIN Spyne doesn't have, and a rare 500 while images are processing, which is temporary.

Recommended flow

When a vehicle arrives without photos, send a generate with all the details you have.
On processing, poll Read status and images every 30 to 60 seconds; stop when every image has an outputImage.
On no_match, schedule a photo shoot as usual.
When you later send the vehicle's real photos through Spyne's API, they replace the Instant set on the same VIN.

Good practice

Send all seven details whenever you have them. It avoids a 400 and gives the most accurate match.
Keep the requestId from each generate with the VIN in your logs.
Keep your API key on your server. Never put it in a browser, an app or a support ticket.

Common questions

Do checks cost anything? No. A check creates nothing and uses no credits.

Does a generate use credits? Yes, the same as processing a photographed vehicle.

Can I generate twice for the same VIN? Yes, safely: the second call answers already_instant. Two calls sent at the same moment may answer 503 for one of them; the set is still built once.

How long do images take? There is no fixed time; they go through the normal processing queue. Poll until they are ready.

Which images should I publish? Only outputImage URLs from Read status and images.

Do Instant images look different? They are studio images of an identical vehicle (same year, make, model, trim, colours and condition) on the rooftop's background. Real photos sent through Spyne's API replace them once the vehicle is shot.

New and used vehicles? Both work. The dealer switches Instant on separately for each; a condition that is off answers INSTANT_NOT_ENABLED.

Who do I contact? Your Spyne account team, with the VIN and requestId.