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

StatusMeaningAction
200SuccessProcess the response
400Bad RequestFix request parameters
401UnauthorizedCheck API key
402Payment RequiredAdd credits to wallet
404Not FoundVerify template ID exists
408TimeoutRetry with shorter timeout
413Payload Too LargeReduce artwork file size
500Internal Server ErrorRetry 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 header
401INVALID_API_KEYKey is wrong or revoked
402INSUFFICIENT_CREDITSWallet balance too low
400MISSING_TEMPLATE_IDtemplate_id not provided
404TEMPLATE_NOT_FOUNDTemplate ID doesn't exist
400MISSING_ARTWORKNo artwork file or URL
400INVALID_ARTWORK_URLURL is not valid http/https
400IMAGE_URL_NOT_FOUNDArtwork URL returned 404
413ARTWORK_FILE_TOO_LARGEFile exceeds 20 MB limit
408IMAGE_FETCH_TIMEOUTDownload timed out

Common 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.jpg

ARTWORK_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.jpg

IMAGE_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:

  1. Check the error code and details fields
  2. Review the API changelog
  3. 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.

Next Steps