Error Codes

Every error response from ThumbAPI follows this format:

{
  "error": "Human-readable error message"
}

HTTP Status Codes

400 — Bad Request

The request body is missing required fields or contains invalid values.

Error Message	Cause	Fix
`title is required`	Missing or empty `title` field	Provide a non-empty `title` string
`format must be one of: youtube, instagram, x, blogpost, linkedin`	Invalid `format` value	Use one of the five valid format strings (or omit `format` and pass `customAssetsId`)
`category must be one of: auto, tech-saas, business-finance, ...`	Invalid `category` value	Use one of the 13 supported category strings, or omit to default to `auto`
`Photo asset required: set photoImage or upload a Personal Photo`	`usePhoto: true` with no saved photo and no inline `photoImage`	Upload a photo in the dashboard or pass `photoImage`
`Logo asset required: set logoImage or upload a Logo`	`useLogo: true` with no saved logo and no inline `logoImage`	Upload a logo in the dashboard or pass `logoImage`
`photoImage exceeds 2MB cap`	Inline photo too large	Compress the photo below 2MB
`logoImage exceeds 1MB cap`	Inline logo too large	Compress the logo below 1MB

401 — Unauthorized

Authentication failed.

Error Message	Cause	Fix
`Missing API key`	No `x-api-key` header	Add `x-api-key: YOUR_KEY`
`Invalid API key`	Key is wrong, expired, or revoked	Check your key in the dashboard

403 — Forbidden

Error Message	Cause	Fix
`API access not enabled`	Your plan does not include API access	Upgrade your plan

429 — Too Many Requests

Error Message	Cause	Fix
`Generation limit exceeded`	You've used all generations for this billing period	Wait for reset or upgrade plan
`Rate limit exceeded`	Too many requests per second	Add backoff/retry logic

500 — Internal Server Error

Error Message	Cause	Fix
`Internal server error`	Something went wrong on our side	Retry after a few seconds. If persistent, contact support

Retry Strategy

For 429 and 500 errors, implement exponential backoff:

async function generateWithRetry(body, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch("https://api.thumbapi.dev/v1/generate", {
      method: "POST",
      headers: {
        "x-api-key": process.env.THUMBAPI_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (res.ok) return res.json();
    if (res.status === 429 || res.status >= 500) {
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
      continue;
    }

    // Client error — don't retry
    throw new Error(`API error ${res.status}: ${(await res.json()).error}`);
  }
  throw new Error("Max retries exceeded");
}

Next Steps

Rate limits — understand your quota and limits
Authentication — fixing auth errors
Endpoint reference — request format details