API reference

Errors

Status codes, error message codes, and how to recover from each.

1 min readLast updated May 17, 2026 Edit this page

All errors share the same JSON envelope. The HTTP status indicates the class of error; the message field is a stable, uppercase code you can switch on.

Generic error shapejson

{
  "success": false,
  "message": "QUOTA_EXCEEDED",
  "feature": "slideshows_per_month"  // optional, depends on code
}

Status codes

Status	Meaning
400	Bad request — validation failed or required field missing.
401	No or invalid credentials — Authorization header missing or token rejected.
402	Payment / quota error — you've exhausted a plan-bound resource.
403	Forbidden — plan doesn't unlock this feature or resource is in another org.
404	Resource not found in your organization.
409	Conflict — e.g. a slug already exists.
422	Semantically invalid — request shape is right but values aren't acceptable.
429	Rate-limited — slow down, see Retry-After.
500	Internal error — safe to retry with exponential backoff.
503	Dependency unavailable — typically Stripe or storage. Retry later.

Error codes you'll see

Code	Status	Description
VALIDATION_ERROR	400	One or more body/query parameters failed validation.
MISSING_AUTH	401	No Authorization header was sent.
INVALID_TOKEN	401	Token expired, malformed, or revoked.
PLAN_LACKS_API	403	Free or Starter plan tried to use API auth — upgrade to Pro+.
PLAN_UPGRADE_REQUIRED	403	Feature is gated to a higher plan (e.g. manual hook refresh).
ORG_NOT_FOUND	403	Token is valid but no active organization is attached.
QUOTA_EXCEEDED	402	Plan-bound resource is exhausted (apps, slideshows/month, etc.). Body includes feature.
APP_NOT_FOUND	404	App id is not in your organization.
HOOK_NOT_FOUND	404	Hook id is not in your organization.
SLIDESHOW_NOT_FOUND	404	Slideshow id is not in your organization.
NO_ACTIVE_APPS	404	Tried to refresh hooks with no ACTIVE apps in the org.
SLUG_EXISTS	409	Auto-generated slug collides — pass a unique slug explicitly.
RATE_LIMITED	429	Per-endpoint rate limit hit. See Retry-After header.
RATE_LIMIT_EXCEEDED	429	Per-org per-minute rate limit hit. See Retry-After header.
GENERATION_FAILED	500	Upstream model error during slideshow generation. Retry safe.
ZIP_GENERATION_FAILED	500	Internal error packing the export ZIP. Retry safe.
ZIP_UPLOAD_FAILED	500	Storage upload failed. Retry safe.
INTERNAL_ERROR	500	Unhandled server error. Retry safe; if persistent, contact support.

Recovery patterns

401 — re-authenticate (issue a new token / check the API key is still active).
402 QUOTA_EXCEEDED — wait for next billing cycle or upgrade plan; check /billing for usage.
403 PLAN_LACKS_API — upgrade to Pro to unlock API auth.
429 — back off using the Retry-After header (seconds).
5xx — exponential backoff with jitter; max ~5 retries before surfacing the error.