Errors and limits

The error shape

Every error has the same shape:

{
  "error": {
    "code": "validation_error",
    "message": "A plain sentence for a person.",
    "details": {}
  }
}

Read code in your software. message is written for people and can change. details is only present for some codes: for validation_error it maps each wrong field to a list of problems, and for quota_exceeded and daily_cap_reached it describes the allowance.

Error codes

Code	Status	Meaning
bad_request	400	The request could not be read, for example a multipart body with no boundary.
unauthorized	401	The Authorization header is missing, or the key is not valid or has been revoked.
payment_required	402	Your plan does not allow that.
quota_exceeded	402	No frames are left. details describes the allowance.
daily_cap_reached	402	The store reached today’s limit of frames.
api_not_enabled	403	The API is switched off for your store.
store_uninstalled	403	The store has uninstalled Shootika, so its keys no longer work.
forbidden	403	The key is not allowed to do that.
not_found	404	Nothing with that id exists in your store. On GET /v1/products/{product_id} also when the id is not a valid id.
method_not_allowed	405	This address does not accept that method. The Allow header lists the ones it does.
conflict	409	That cannot be done in the current state.
external_id_taken	409	Another product already uses that external_id.
catalog_managed_by_shopify	409	The store is a Shopify store, whose products come from Shopify.
image_locked	409	The photo is in use by a running shoot, or is itself an approved frame.
scene_generating	409	The scene is still being prepared.
scene_failed	409	The scene could not be prepared. Request it again.
family_unsupported	409	The product is not clothing.
not_ready	409	The frame is not finished, or it failed or was canceled.
attach_conflict	409	The frame is already approved or its approval is still running; or, when taking an approval down, it is not approved.
result_purged	409	The frame expired and was deleted.
approval_unavailable	409	The frame cannot be approved in this store.
media_processing_failed	409	Shopify could not process the frame. Try again.
idempotency_conflict	409	The Idempotency-Key was used for a different request.
idempotency_in_progress	409	A request with the same Idempotency-Key is still running.
validation_error	422	Some of the request is not valid. details names the fields.
invalid_url	422	The image address is not an allowed one.
unreachable_url	422	The image address could not be fetched.
not_an_image	422	The file is not a PNG, JPEG or WebP image.
too_large	422	The image is over 15 MB.
source_image_too_small	422	The photo’s short side is under 600 pixels.
scene_unsupported	422	The scene does not suit this product. Pick another scene.
rate_limited	429	More than 120 requests in a minute with this key.
internal_error	500	Something went wrong on our side. Try again.
service_busy	503	Shootika is busy right now. Try again in a moment.
upload_failed	503	The photo could not be stored. Try again in a moment.

Which errors are worth retrying is on Idempotency and retries.

Rate limit

Each API key may make 120 requests a minute. Above that the API answers 429 rate_limited with a Retry-After header: wait that many seconds, then send the request again. Polling counts toward the limit like any other request.

A 503 service_busy can also carry a Retry-After header. Wait that long before retrying.

Limits

What	Limit
Requests per API key	120 a minute
page_size on a list	Default 24, at most 100
Product title	500 characters
Product external_id	255 characters, unique among your products
image_urls on one create	10
An image url	2048 characters
Photo file	PNG, JPEG or WebP, at most 15 MB
Photo to shoot	Short side at least 600 pixels
Fetching a photo from a web address	http or https on port 80 or 443, a public address, no redirects, at most 20 seconds
Fetching all image_urls of one create	At most 30 seconds together
Idempotency-Key	1 to 255 characters; a 2xx answer is replayed for 24 hours
Frames a store may make in a day	quota.daily.cap in GET /v1/account, counted per UTC day; 0 means no daily limit
An unapproved frame	Deleted at its expires_at