Error Handling
The Mockupanda API uses standard HTTP status codes and returns detailed error messages in JSON format. This page covers all error codes, how to handle them, and best practices.
Error Response Format
All errors return JSON with this structure:
{
"error": "Human-readable error message",
"code": "MACHINE_READABLE_ERROR_CODE",
"details": { /* Optional additional context */ },
"hint": "Optional suggestion for fixing the error",
"request_id": "Generate requests: the id it shows under in Dashboard > Logs"
}Example Error
{
"error": "Insufficient account balance. Add funds in Billing to continue.",
"code": "INSUFFICIENT_CREDITS",
"details": {
"required_cents": 1,
"balance_cents": 0
},
"hint": "Top up your API wallet from Dashboard > Billing and retry.",
"request_id": "013b73a7-9d8e-4a5d-9e45-251197bd75a1"
}Request IDs and logs
Every response from POST /api/v1/mockups/generate, successful or not, carries an X-Request-Id header. JSON responses repeat it as request_id. Each request also shows up in DashboardLogs within a second, with the body you sent, the response you got and what it cost, so you can search for that id there. Include it when you contact support.
HTTP Status Codes
| Status | Meaning | Action |
|---|---|---|
200 | Success | Process the response |
400 | Bad Request | Fix request parameters |
401 | Unauthorized | Check API key |
402 | Payment Required | Add credits to wallet |
404 | Not Found | Verify template ID exists |
408 | Timeout | Retry with shorter timeout |
413 | Payload Too Large | Reduce artwork file size |
500 | Internal Server Error | Retry with exponential backoff |
Error Codes
{
"error": "Insufficient account balance. Add funds in Billing to continue.",
"code": "INSUFFICIENT_CREDITS",
"details": { "required_cents": 1, "balance_cents": 0 },
"hint": "Top up your API wallet from Dashboard > Billing and retry."
}401MISSING_API_KEYNo Authorization header401INVALID_API_KEYKey is wrong or revoked402INSUFFICIENT_CREDITSWallet balance too low400MISSING_TEMPLATE_IDtemplate_id not provided404TEMPLATE_NOT_FOUNDTemplate ID doesn't exist400MISSING_ARTWORKNo artwork file or URL400INVALID_ARTWORK_URLURL is not valid http/https400IMAGE_URL_NOT_FOUNDArtwork URL returned 404413ARTWORK_FILE_TOO_LARGEFile exceeds 20 MB limit408IMAGE_FETCH_TIMEOUTDownload timed outCommon Errors
Authentication Errors
MISSING_API_KEY
{
"error": "Missing API key. Use Authorization: Bearer mk_xxx",
"code": "MISSING_API_KEY"
}Cause: No Authorization header in request.
Fix: Add the header:
-H "Authorization: Bearer YOUR_API_KEY"INVALID_API_KEY
{
"error": "Invalid or revoked API key",
"code": "INVALID_API_KEY"
}Cause: API key is incorrect, expired, or revoked.
Fix: Verify your API key in DashboardAPI keys. Generate a new key if needed.
Payment Errors
INSUFFICIENT_CREDITS
{
"error": "Insufficient account balance. Add funds in Billing to continue.",
"code": "INSUFFICIENT_CREDITS",
"details": {
"required_cents": 1,
"balance_cents": 0
},
"hint": "Top up your API wallet from Dashboard > Billing and retry.",
"request_id": "013b73a7-9d8e-4a5d-9e45-251197bd75a1"
}Cause: Your wallet doesn't have enough credits.
Fix: Add credits at DashboardBilling. Each mockup costs 1 credit ($0.01 USD).
Template Errors
MISSING_TEMPLATE_ID
{
"error": "template_id or template_ids is required",
"code": "MISSING_TEMPLATE_ID"
}Cause: No template_id parameter in request.
Fix: Add the template_id parameter:
-F "template_id=bedroom-poster-01"TEMPLATE_NOT_FOUND
{
"error": "Template not found: invalid-id",
"code": "TEMPLATE_NOT_FOUND",
"details": {
"missing_template_ids": ["invalid-id"]
}
}Cause: Template ID doesn't exist.
Fix: Verify the template ID exists at mockupanda.com/editor or via the templates endpoint.
Artwork Errors
MISSING_ARTWORK
{
"error": "Artwork is required. Provide artwork (file/URL) or artwork_urls for multi-frame.",
"code": "MISSING_ARTWORK"
}Cause: No artwork URL provided.
Fix: Add either artwork_url (one frame) or artwork_urls (several frames):
-F "artwork_url=https://example.com/art.jpg"INVALID_ARTWORK_URL
{
"error": "artwork_url must start with http:// or https://",
"code": "INVALID_ARTWORK_URL"
}Cause: URL is malformed or uses an unsupported protocol.
Fix: Ensure the URL starts with http:// or https://:
-F "artwork_url=https://example.com/art.jpg"IMAGE_URL_NOT_FOUND
{
"error": "One of the image URLs does not exist (404).",
"code": "IMAGE_URL_NOT_FOUND",
"hint": "Check the artwork_url/artwork_urls value and make sure the URL is public and correct."
}Cause: The artwork URL returned a 404 error.
Fix: Verify the URL is publicly accessible:
curl -I https://example.com/art.jpgARTWORK_FILE_TOO_LARGE
{
"error": "Artwork file is too large (max 20 MB)",
"code": "ARTWORK_FILE_TOO_LARGE"
}Cause: Artwork file exceeds 20 MB limit.
Fix: Compress or resize the artwork:
# Using ImageMagick
convert input.jpg -quality 85 -resize 3000x3000 output.jpgIMAGE_FETCH_TIMEOUT
{
"error": "Image download timed out.",
"code": "IMAGE_FETCH_TIMEOUT",
"hint": "Retry with a faster image host or a smaller source image."
}Cause: Artwork URL took too long to respond.
Fix: Use a CDN or faster hosting for artwork files.
Error Handling Best Practices
Retry Logic
Implement exponential backoff for transient errors:
async function generateMockupWithRetry(params, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
const response = await generateMockup(params);
return response;
} catch (error) {
// Retry on 408 and 500+ errors
if ([408, 500, 502, 503, 504].includes(error.status)) {
const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
await sleep(delay);
continue;
}
// Don't retry on client errors (400, 401, 402, 404, 413)
throw error;
}
}
throw new Error('Max retries exceeded');
}Error Logging
Log errors with context for debugging:
try {
const response = await generateMockup(params);
} catch (error) {
console.error('Mockup generation failed:', {
code: error.code,
message: error.error,
details: error.details,
params: params,
timestamp: new Date().toISOString()
});
throw error;
}Messages for Your Users
Turn error codes into messages your users can understand:
const ERROR_MESSAGES = {
INSUFFICIENT_CREDITS: 'Your account balance is too low. Please add credits.',
INVALID_API_KEY: 'Invalid API key. Please check your configuration.',
TEMPLATE_NOT_FOUND: 'The selected template is no longer available.',
ARTWORK_FILE_TOO_LARGE: 'Your artwork file is too large. Please use a smaller image.'
};
function getUserMessage(errorCode) {
return ERROR_MESSAGES[errorCode] || 'An unexpected error occurred. Please try again.';
}Graceful Degradation
Handle errors gracefully in your application:
async function generateMockupSafely(params) {
try {
return await generateMockup(params);
} catch (error) {
if (error.code === 'INSUFFICIENT_CREDITS') {
// Redirect to billing page
window.location.href = '/billing';
} else if (error.code === 'TEMPLATE_NOT_FOUND') {
// Fallback to default template
params.template_id = 'bedroom-poster-01';
return await generateMockup(params);
} else {
// Show error to user
showError(getUserMessage(error.code));
return null;
}
}
}Monitoring
Monitor error rates to detect issues early:
const errorMetrics = {
total: 0,
byCode: {}
};
function trackError(error) {
errorMetrics.total++;
errorMetrics.byCode[error.code] = (errorMetrics.byCode[error.code] || 0) + 1;
// Alert if error rate exceeds threshold
if (errorMetrics.total > 100) {
console.warn('High error rate detected:', errorMetrics);
}
}Support
If you encounter an error not documented here:
- Check the error
codeanddetailsfields - Review the API changelog
- Contact support via the feedback button in your dashboard
Include the full error response and your request parameters (without your API key) for faster resolution.