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 | Invalid format value | Use one of the four valid format strings |
imageStyle must be one of: faceless, with-image, with-logo | Invalid imageStyle | Use one of the three valid style strings |
personImage is required when imageStyle is with-image or with-logo | Missing image for person/logo style | Include base64-encoded image in personImage |
401 — Unauthorized
Authentication failed.
| Error Message | Cause | Fix |
|---|
Missing authorization header | No Authorization header | Add Authorization: Bearer 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: {
"Authorization": `Bearer ${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
