Error Handling

1{
2  "detail": "Human-readable error message",
3  "success": false
4}

1{
2  "error_code": "PSD_PARSE_FAILED",
3  "message": "Failed to parse PSD file",
4  "detail": "Failed to parse PSD file",
5  "details": {
6    "reason": "Invalid or corrupted PSD/PSB header",
7    "suggestion": "Re-export the PSD from Adobe Photoshop"
8  },
9  "success": false
10}

1{
2  "detail": "Validation error",
3  "errors": [
4    {
5      "field": "body -> psd_file_url",
6      "message": "Missing required field: body -> psd_file_url"
7    }
8  ],
9  "success": false
10}

1{
2  "error": "credits_exhausted",
3  "message": "You have used all 500 trial credits. Add a payment method to keep rendering, or start a plan.",
4  "actions": [
5    {
6      "label": "Add a payment method",
7      "url": "https://sudomock.com/dashboard/billing?action=topup#payg-section"
8    },
9    {
10      "label": "Start a plan",
11      "url": "https://sudomock.com/pricing"
12    }
13  ]
14}

1{
2  "error": "insufficient_balance",
3  "message": "Your balance does not cover this request. Add balance to continue.",
4  "actions": [
5    {
6      "label": "Add balance",
7      "url": "https://sudomock.com/dashboard/billing?action=topup#payg-section"
8    },
9    {
10      "label": "View billing",
11      "url": "https://sudomock.com/dashboard/billing"
12    }
13  ],
14  "credits_reset_at": "2026-09-01T00:00:00Z"
15}

1{
2  "error": "payment_required",
3  "message": "Your latest subscription payment could not be completed. Update your payment method to continue.",
4  "actions": [
5    {
6      "label": "Update Payment Method",
7      "url": "https://sudomock.com/dashboard/billing?action=update-payment"
8    },
9    {
10      "label": "View billing",
11      "url": "https://sudomock.com/dashboard/billing"
12    }
13  ]
14}

1{
2  "detail": "Rate limit exceeded. Please slow down and try again.",
3  "error": {
4    "type": "rate_limit_exceeded",
5    "code": "RATE_LIMIT_EXCEEDED",
6    "limit": 1000,
7    "remaining": 0,
8    "reset_seconds": 42,
9    "retry_after": 42,
10    "resource": "api"
11  }
12}

1{
2  "success": true,
3  "data": { "print_files": [/* ... */] },
4  "warnings": [
5    {
6      "code": "TEXT_FONT_FALLBACK",
7      "message": "Original font not in catalog; rendered in a default font."
8    }
9  ]
10}

1// Handling PSD error codes
2if (response.status === 400 || response.status === 500) {
3  const error = await response.json();
4
5  if (error.error_code) {
6    // PSD processing error
7    switch (error.error_code) {
8      case 'NO_SMART_OBJECTS':
9        console.error(`Found ${error.details.total_layers} layers but no visible Smart Object or text layer`);
10        break;
11      case 'UNSUPPORTED_SMART_OBJECT_FORMAT':
12        console.error(`Layer "${error.details.layer_name}" uses ${error.details.format.toUpperCase()} format`);
13        break;
14      default:
15        console.error(error.details?.suggestion || error.message);
16    }
17  }
18}

1// Handling 402 responses
2if (response.status === 402) {
3  const error = await response.json();
4
5  switch (error.error) {
6    case 'credits_exhausted':
7      // Plan credits spent and the balance cannot cover this request
8      console.log('Credits depleted. Resets at:', error.credits_reset_at);
9      break;
10    case 'insufficient_balance':
11      // Subscribed, but the prepaid balance is too low. Send them to top up.
12      console.log('Balance too low:', error.message);
13      break;
14    case 'payment_required':
15      // Subscription payment needs attention
16      console.error('Payment required:', error.message);
17      break;
18    case 'no_subscription':
19      // No active plan
20      console.log('No subscription found');
21      break;
22    default:
23      // New codes ship without a client release. Always keep this branch:
24      // error.message and error.actions are populated for every code.
25      console.warn('Unhandled billing error:', error.error, error.message);
26  }
27
28  // Actions array contains direct links
29  for (const action of error.actions) {
30    console.log(`  ${action.label}: ${action.url}`);
31  }
32}

1{
2  "error_code": "OUTPUT_RESOLUTION_LIMIT",
3  "message": "Your account is in trial, so output is capped at 1024px.",
4  "detail": "Your account is in trial, so output is capped at 1024px.",
5  "details": {
6    "requested_width": 4096,
7    "limit": 1024,
8    "suggestion": "Lower image_size to 1024 or below, or add a payment method to render at full width."
9  },
10  "success": false
11}

1// Response - No visible personalizable layers
2{
3  "error_code": "NO_SMART_OBJECTS",
4  "message": "The PSD has no visible personalizable layers.",
5  "detail": "The PSD has no visible personalizable layers.",
6  "details": {
7    "total_layers": 12,
8    "hidden_smart_objects": 0,
9    "suggestion": "Make at least one personalizable layer visible, then upload the PSD again."
10  },
11  "success": false
12}
13
14// Response - Vector Smart Object
15{
16  "error_code": "UNSUPPORTED_SMART_OBJECT_FORMAT",
17  "message": "Smart object 'Logo' contains unsupported format: AI",
18  "detail": "Smart object 'Logo' contains unsupported format: AI",
19  "details": {
20    "layer_name": "Logo",
21    "format": "ai",
22    "supported_formats": ["png", "jpg", "jpeg", "tif", "tiff", "gif", "bmp", "webp", "psd", "psb"],
23    "suggestion": "Vector Smart Objects (AI) are not currently supported. To fix: In Photoshop, right-click the Smart Object layer > 'Rasterize Layer', then re-save your PSD."
24  },
25  "success": false
26}

1// Response
2{
3  "detail": "Not authenticated",
4  "success": false
5}

1// Request missing required field
2POST /api/v1/psd/upload
3{
4  "psd_name": "My Mockup"
5  // Missing: psd_file_url (required)
6}
7
8// Response
9{
10  "detail": "Validation error",
11  "errors": [
12    {"field": "body -> psd_file_url", "message": "Missing required field: body -> psd_file_url"}
13  ],
14  "success": false
15}

1// Response
2{
3  "detail": "Mockup not found",
4  "success": false
5}

1// Request with invalid field type
2POST /api/v1/renders
3{
4  "mockup_uuid": "valid-uuid",
5  "smart_objects": "should-be-array"
6}
7
8// Response
9{
10  "detail": "Validation error",
11  "errors": [
12    {"field": "body -> smart_objects", "message": "Invalid type for field: body -> smart_objects"}
13  ],
14  "success": false
15}
16
17// Request with invalid export options
18POST /api/v1/renders
19{
20  "mockup_uuid": "valid-uuid",
21  "smart_objects": [...],
22  "export_options": {
23    "image_size": 20000,  // Max is 10000
24    "quality": 150        // Max is 100
25  }
26}
27
28// Response
29{
30  "detail": "Validation error",
31  "errors": [
32    {"field": "body -> export_options -> image_size", "message": "Invalid number for field: body -> export_options -> image_size"},
33    {"field": "body -> export_options -> quality", "message": "Invalid number for field: body -> export_options -> quality"}
34  ],
35  "success": false
36}

1// 400 - Artwork URL returned 404 (upstream user-side issue; do NOT retry blindly)
2{
3  "detail": "Image not found for 'Main Design'. example.com returned HTTP 404.",
4  "success": false
5}
6
7// 400 - Artwork URL is blocked or returns 403
8{
9  "detail": "Image URL blocked or inaccessible for 'Main Design'. example.com returned HTTP 403.",
10  "success": false
11}
12
13// 502 - Artwork source is temporarily down (safe to retry)
14{
15  "detail": "The image source for 'Main Design' is temporarily unavailable. cdn.example.com returned HTTP 503. Please try again later.",
16  "success": false
17}
18
19// 502 - Artwork URL is unreachable (network-level)
20{
21  "detail": "Failed to download image for 'Main Design'. The image source may be unreachable.",
22  "success": false
23}

1// Response
2{
3  "error_code": "INVALID_VIDEO_DURATION",
4  "message": "duration_seconds is not allowed for the selected model.",
5  "allowed_durations": [4, 6],
6  "suggestion": "Pick a value from allowed_durations.",
7  "detail": "duration_seconds is not allowed for the selected model.",
8  "success": false
9}

1// Request without Bearer token
2POST /api/v1/api-keys
3Authorization: (missing)
4
5// Response
6{
7  "detail": "Not authenticated",
8  "success": false
9}

1// Request to delete non-existent key
2DELETE /api/v1/api-keys/non-existent-id
3
4// Response
5{
6  "detail": "API key not found",
7  "success": false
8}

1// Request with invalid expiration
2POST /api/v1/api-keys
3{
4  "name": "My Key",
5  "expires_in_days": 5000  // Max is 3650
6}
7
8// Response
9{
10  "detail": "Validation error",
11  "errors": [
12    {"field": "body -> expires_in_days", "message": "Invalid number for field: body -> expires_in_days"}
13  ],
14  "success": false
15}

1// Generic server error (unhandled exception)
2{
3  "detail": "Internal server error",
4  "success": false
5}
6
7// PSD processing server error (includes error_code)
8{
9  "error_code": "INTERNAL_ERROR",
10  "message": "The file could not be processed. Please try again.",
11  "suggestion": "Please try again. If the problem persists, contact support.",
12  "success": false
13}

1async function apiRequest(url, options, maxRetries = 3) {
2  for (let attempt = 0; attempt < maxRetries; attempt++) {
3    try {
4      const response = await fetch(url, options);
5
6      // Success
7      if (response.ok) {
8        return response.json();
9      }
10
11      // Rate or concurrent limit exceeded - use Retry-After header
12      if (response.status === 429) {
13        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
14        console.log(`Limit exceeded. Waiting ${retryAfter}s...`);
15        await sleep(retryAfter * 1000);
16        continue;
17      }
18
19      // Server error or upstream error - exponential backoff
20      if (response.status >= 500) {
21        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
22        console.log(`Server error ${response.status}. Retrying in ${delay}ms...`);
23        await sleep(delay);
24        continue;
25      }
26
27      // Client error - don't retry, throw immediately
28      const error = await response.json();
29      throw new Error(error.detail || error.message || JSON.stringify(error));
30
31    } catch (networkError) {
32      // Network error - retry with backoff
33      if (attempt < maxRetries - 1) {
34        const delay = Math.pow(2, attempt) * 1000;
35        await sleep(delay);
36        continue;
37      }
38      throw networkError;
39    }
40  }
41
42  throw new Error('Max retries exceeded');
43}
44
45function sleep(ms) {
46  return new Promise(resolve => setTimeout(resolve, ms));
47}
48
49// Optional: Check remaining requests before making calls
50function checkRateLimitHeaders(response) {
51  const limit = response.headers.get('RateLimit-Limit');
52  const remaining = response.headers.get('RateLimit-Remaining');
53  const reset = response.headers.get('RateLimit-Reset');
54  const policy = response.headers.get('RateLimit-Policy');
55
56  console.log(`Rate limit: ${remaining}/${limit} remaining, resets in ${reset}s (policy: ${policy})`);
57
58  // Check concurrent usage
59  const concurrentLimit = response.headers.get('X-Concurrent-Limit');
60  const concurrentUsed = response.headers.get('X-Concurrent-Used');
61  const concurrentRemaining = response.headers.get('X-Concurrent-Remaining');
62
63  if (concurrentLimit) {
64    console.log(`Concurrent: ${concurrentUsed}/${concurrentLimit} in use, ${concurrentRemaining} remaining`);
65  }
66
67  // Warning when running low
68  if (remaining && parseInt(remaining) < 100) {
69    console.warn('Rate limit running low, consider slowing down');
70  }
71}

1async function handleRenderRequest(payload) {
2  const response = await fetch('https://api.sudomock.com/api/v1/renders', {
3    method: 'POST',
4    headers: {
5      'x-api-key': process.env.SUDOMOCK_API_KEY,
6      'Content-Type': 'application/json'
7    },
8    body: JSON.stringify(payload)
9  });
10
11  if (response.status === 422) {
12    const error = await response.json();
13
14    // Parse sanitized validation errors
15    for (const err of error.errors) {
16      console.error(`Validation error at ${err.field}: ${err.message}`);
17
18      // Example message: "Invalid number for field: body -> export_options -> quality"
19    }
20
21    throw new Error('Validation failed: ' + error.errors.map(e => e.message).join(', '));
22  }
23
24  if (!response.ok) {
25    const error = await response.json();
26    throw new Error(error.detail || error.message);
27  }
28
29  return response.json();
30}

1{
2  "detail": "Rate limit exceeded. Please slow down and try again.",
3  "error": {
4    "type": "rate_limit_exceeded",
5    "code": "RATE_LIMIT_EXCEEDED",
6    "limit": 1000,
7    "remaining": 0,
8    "reset_seconds": 42,
9    "retry_after": 42,
10    "resource": "api"
11  }
12}

1{
2  "detail": "Max concurrent render requests exceeded. Your account is in trial, so it allows 1 concurrent render request(s). Retry in a few seconds, or add a payment method to raise this limit.",
3  "error": {
4    "type": "concurrent_limit_exceeded",
5    "code": "CONCURRENT_LIMIT_EXCEEDED",
6    "limit": 1,
7    "current": 2,
8    "remaining": 0,
9    "resource": "concurrent-render"
10  }
11}

1{
2  "detail": "Max concurrent render requests exceeded. Your account allows 10 concurrent render request(s). Retry in a few seconds, or move to a plan with higher concurrency.",
3  "error": {
4    "type": "concurrent_limit_exceeded",
5    "code": "CONCURRENT_LIMIT_EXCEEDED",
6    "limit": 10,
7    "current": 11,
8    "remaining": 0,
9    "resource": "concurrent-render"
10  }
11}

1{
2  "detail": "Max concurrent render requests exceeded. Your account allows 25 concurrent render request(s), which is the highest concurrency we offer. Retry in a few seconds.",
3  "error": {
4    "type": "concurrent_limit_exceeded",
5    "code": "CONCURRENT_LIMIT_EXCEEDED",
6    "limit": 25,
7    "current": 26,
8    "remaining": 0,
9    "resource": "concurrent-render"
10  }
11}

1async function handle429(response) {
2  const error = await response.json();
3
4  // Get retry delay from header or error body
5  const retryAfter = parseInt(
6    response.headers.get('Retry-After') ||
7    error.error?.retry_after ||
8    '60'
9  );
10
11  // Check error type
12  if (error.error?.type === 'rate_limit_exceeded') {
13    console.log(`Rate limited. Waiting ${retryAfter}s...`);
14  } else if (error.error?.type === 'concurrent_limit_exceeded') {
15    console.log(`Concurrent limit hit. Resource: ${error.error.resource}`);
16  }
17
18  // Wait and retry
19  await new Promise(r => setTimeout(r, retryAfter * 1000));
20  return retry();
21}