API

Errors

Every non-2xx response uses the same error envelope.

#Error envelope

Every non-2xx response returns a JSON object with a single error key:

JSON

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits: need 10, have 3 remaining."
  }
}

code is a stable machine-readable identifier. message is a human-readable description that may include contextual detail.

Code	HTTP	When
`invalid_key`	401	Missing, malformed, or revoked API key.
`api_not_on_plan`	403	Your plan doesn't include API access. Pro plan required.
`insufficient_credits`	402	Not enough credits remaining this billing period.
`deck_limit`	402	Deck count is at the plan limit. Upgrade to create more.
`brand_limit`	402	Brand count is at the plan limit. Upgrade to create more.
`invalid_input`	422	Request body missing required fields or failed validation (e.g. `input` too long, missing `title`).
`not_found`	404	The resource doesn't exist or belongs to a different user.
`rate_limit`	429	Too many `generate` requests per second for your plan's RPS limit. Retry after 1 second.
`internal_error`	500	An unexpected server error. The message may contain details.

The rate_limit code (HTTP 429) applies to POST /v1/generate only. Read-only endpoints are not rate-limited.

A 402 covers three distinct situations — always check error.code:

insufficient_credits — you've used your monthly allowance. Wait for the next billing period or upgrade.
deck_limit — you've reached the maximum deck count for your plan. Delete a deck or upgrade.
brand_limit — you've reached the maximum brand count for your plan. Delete a brand or upgrade.

Safe to retry (idempotent reads):

Not safe to retry without checking first:

POST /v1/generate — each call deducts 10 credits and creates a new job.
POST /v1/decks/{id}/publish — idempotent by effect but each call creates a version snapshot.

500 internal_error responses are safe to retry with exponential backoff.