Errors

Every error of the API has the same JSON body, whatever the endpoint:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Request validation failed.",
    "requestId": "1a1ae233-21d0-4d7a-9549-d4c6b482f2f3",
    "docUrl": "https://api.storeshot.art/v1/docs/errors#INVALID_INPUT",
    "details": { "issues": [{ "location": "body", "path": ["app"], "message": "Required" }] }
  }
}

• code is stable (UPPER_SNAKE): branch on it, never on message, which may change.
• requestId equals the X-Request-Id response header. Quote it when you contact support.
• details is optional and specific to the code (validation issues, the required scope, the credits needed, the seconds to wait); the catalogue below says what each code carries.

Handle an error

This request leaves out required fields, so it answers 400 INVALID_INPUT with one entry per problem in details.issues:

curl -sS https://api.storeshot.art/v1/generations \
  -H "Authorization: Bearer $STORESHOT_API_KEY" -H 'Content-Type: application/json' \
  -d '{"inputs":[],"store":"app_store"}' \
  | jq '{code: .error.code, requestId: .error.requestId, issues: [.error.details.issues[] | "\(.path | join(".")): \(.message)"]}'

const res = await fetch('https://api.storeshot.art/v1/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.STORESHOT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ inputs: [], store: 'app_store' }),
});
if (!res.ok) {
  const { error } = await res.json();
  console.log(res.status, error.code, error.requestId);
  for (const issue of error.details?.issues ?? []) console.log(issue.path.join('.'), issue.message);
}

import os, requests

res = requests.post(
    "https://api.storeshot.art/v1/generations",
    headers={"Authorization": f"Bearer {os.environ['STORESHOT_API_KEY']}"},
    json={"inputs": [], "store": "app_store"},
)
if not res.ok:
    error = res.json()["error"]
    print(res.status_code, error["code"], error["requestId"])
    for issue in error.get("details", {}).get("issues", []):
        print(".".join(str(p) for p in issue["path"]), issue["message"])

What to retry

Requests that create something (POST /generations, POST /screenshot-sets) are safe to retry with the same Idempotency-Key: a request that already succeeded is answered again instead of running twice. A generation that ends failed reports its reason in its own error.code (GENERATION_FAILED, GENERATION_TIMEOUT, …) and, with a live key, is refunded; create a new generation to try again.

Error codes

Every code has its own anchor on this page, for example /docs/errors/#RATE_LIMITED. Reserved codes are part of the contract but not sent yet.