Error Handling

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

1{
2  "detail": [
3    {
4      "loc": ["body", "field_name"],
5      "msg": "Error message describing the issue",
6      "type": "error_type"
7    }
8  ]
9}

1// Request with invalid URL
2POST /api/v1/psd/upload
3{
4  "psd_file_url": "not-a-valid-url"
5}
6
7// Response
8{
9  "success": false,
10  "detail": "Invalid PSD file URL format"
11}

1// Request without API key
2POST /api/v1/psd/upload
3X-API-KEY: (missing or invalid)
4
5// Response
6{
7  "success": false,
8  "detail": "Invalid or missing API key"
9}

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": [
11    {
12      "loc": ["body", "psd_file_url"],
13      "msg": "field required",
14      "type": "value_error.missing"
15    }
16  ]
17}

1// Request with invalid asset URL
2POST /api/v1/renders
3{
4  "mockup_uuid": "valid-uuid",
5  "smart_objects": [{
6    "uuid": "so-uuid",
7    "asset": { "url": "not-accessible-url" }
8  }]
9}
10
11// Response
12{
13  "success": false,
14  "detail": "Unable to fetch asset from provided URL"
15}

1// Request with invalid mockup_uuid
2POST /api/v1/renders
3{
4  "mockup_uuid": "non-existent-uuid",
5  "smart_objects": [...]
6}
7
8// Response
9{
10  "success": false,
11  "detail": "Mockup not found"
12}

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": [
11    {
12      "loc": ["body", "smart_objects"],
13      "msg": "value is not a valid list",
14      "type": "type_error.list"
15    }
16  ]
17}
18
19// Request with invalid export options
20POST /api/v1/renders
21{
22  "mockup_uuid": "valid-uuid",
23  "smart_objects": [...],
24  "export_options": {
25    "image_size": 10000,  // Max is 8000
26    "quality": 150        // Max is 100
27  }
28}
29
30// Response
31{
32  "detail": [
33    {
34      "loc": ["body", "export_options", "image_size"],
35      "msg": "ensure this value is less than or equal to 8000",
36      "type": "value_error.number.not_le"
37    },
38    {
39      "loc": ["body", "export_options", "quality"],
40      "msg": "ensure this value is less than or equal to 100",
41      "type": "value_error.number.not_le"
42    }
43  ]
44}

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

1// Request to delete non-existent key
2DELETE /api/v1/api-keys/non-existent-id
3
4// Response
5{
6  "success": false,
7  "detail": "API key not found"
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": [
11    {
12      "loc": ["body", "expires_in_days"],
13      "msg": "ensure this value is less than or equal to 3650",
14      "type": "value_error.number.not_le"
15    }
16  ]
17}

1// Response on server error
2{
3  "success": false,
4  "detail": "An unexpected error occurred. Please try again."
5}

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 - exponential backoff
20      if (response.status >= 500) {
21        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
22        console.log(`Server error. 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 || 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  
55  console.log(`Rate limit: ${remaining}/${limit} remaining, resets in ${reset}s`);
56  
57  // Warning when running low
58  if (remaining && parseInt(remaining) < 100) {
59    console.warn('Rate limit running low, consider slowing down');
60  }
61}

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 validation errors
15    for (const err of error.detail) {
16      const fieldPath = err.loc.join('.');
17      console.error(`Validation error at ${fieldPath}: ${err.msg}`);
18      
19      // Example: "body.export_options.quality: ensure this value is less than or equal to 100"
20    }
21    
22    throw new Error('Validation failed: ' + error.detail.map(e => e.msg).join(', '));
23  }
24
25  if (!response.ok) {
26    const error = await response.json();
27    throw new Error(error.detail);
28  }
29
30  return response.json();
31}

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    "retry_after": 42
9  }
10}

1{
2  "detail": "Max concurrent render requests exceeded. Your plan (Pro) allows 10 concurrent render request(s).",
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}

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}