What are the best practices for using a mockup API?

Key practices include: batch requests when possible, cache responses, use webhooks instead of polling, handle errors gracefully, validate inputs before API calls, and optimize image sizes for your use case.

How should I handle API rate limits?

Implement exponential backoff on rate limit errors, queue requests during high-volume periods, distribute processing across time windows, and consider upgrading your plan if consistently hitting limits.

What's the best way to structure mockup API requests?

Group related operations into single requests where possible, use consistent naming for Smart Object targets, include all required parameters upfront, and specify output format/quality to avoid unnecessary re-processing.

How do I optimize mockup API performance?

Pre-process and cache templates, use CDN URLs for input images, request appropriate output dimensions (not larger than needed), enable compression for transfers, and parallelize independent render requests.

What error handling should I implement for mockup APIs?

Handle network timeouts, validate API responses, retry transient errors with backoff, log failures for debugging, implement fallbacks for critical paths, and alert on repeated failures. Never assume success.

API Integration Best Practices

Building robust API integrations means handling limits and errors gracefully. This guide covers best practices for parallel processing, retry logic, and error handling - so your mockup pipeline never breaks.

Understanding Parallel Limits

SudoMock uses parallel limits to ensure fair usage and consistent performance. These limits determine how many simultaneous requests you can have in-flight at once:

Plan	Parallel Renders	Parallel Uploads
Free	1	1
Starter	3	2
Pro	10	5
Scale	25	10

Response Headers

Every API response includes parallel limit headers:

x-concurrent-limit - Your parallel limit
x-concurrent-remaining - Available slots
Retry-After - Seconds to wait (only on 429 responses)

Handling 429 Errors

When you exceed parallel limits, the API returns 429 Parallel Limit Reached. Here's how to handle it properly:

Basic retry with backoff

javascript

1async function renderWithRetry(payload, maxRetries = 3) {
2  for (let attempt = 0; attempt < maxRetries; attempt++) {
3    const response = await fetch('https://api.sudomock.com/api/v1/renders', {
4      method: 'POST',
5      headers: {
6        'X-API-KEY': API_KEY,
7        'Content-Type': 'application/json'
8      },
9      body: JSON.stringify(payload)
10    });
11
12    if (response.ok) {
13      return response.json();
14    }
15
16    if (response.status === 429) {
17      // Get retry delay from header, or use short backoff
18      const retryAfter = response.headers.get('Retry-After');
19      const delay = retryAfter
20        ? parseInt(retryAfter) * 1000
21        : Math.pow(2, attempt) * 1000;
22
23      console.log(`Parallel limit reached. Retrying in \${delay}ms...`);
24      await sleep(delay);
25      continue;
26    }
27
28    // Other errors - don't retry
29    throw new Error(`API error: \${response.status}`);
30  }
31
32  throw new Error('Max retries exceeded');
33}
34
35function sleep(ms) {
36  return new Promise(resolve => setTimeout(resolve, ms));
37}

Exponential Backoff

For retry logic, exponential backoff prevents overwhelming the API. The delay doubles with each retry attempt:

Retry 1

First attempt

Retry 2

Second attempt

Retry 3

Third attempt

Retry 4

Fourth attempt

Exponential backoff with jitter

javascript

1function getBackoffDelay(attempt, baseDelay = 1000) {
2  // Exponential: 1s, 2s, 4s, 8s...
3  const exponentialDelay = Math.pow(2, attempt) * baseDelay;
4
5  // Add jitter (0-25% random) to prevent thundering herd
6  const jitter = exponentialDelay * Math.random() * 0.25;
7
8  // Cap at 30 seconds
9  return Math.min(exponentialDelay + jitter, 30000);
10}

Why Jitter?

When multiple clients hit limits simultaneously, they all retry at the same time - causing another limit breach. Adding random jitter spreads out retries.

Parallel Processing Strategy

For high-volume workloads, process requests in parallel up to your plan's limit:

Parallel worker pool

javascript

1class ParallelQueue {
2  constructor(parallelLimit) {
3    this.queue = [];
4    this.activeCount = 0;
5    this.parallelLimit = parallelLimit;
6    this.results = [];
7  }
8
9  async add(payload) {
10    return new Promise((resolve, reject) => {
11      this.queue.push({ payload, resolve, reject });
12      this.process();
13    });
14  }
15
16  async process() {
17    while (this.queue.length > 0 && this.activeCount < this.parallelLimit) {
18      const { payload, resolve, reject } = this.queue.shift();
19      this.activeCount++;
20
21      renderWithRetry(payload)
22        .then(result => {
23          resolve(result);
24          this.activeCount--;
25          this.process(); // Process next in queue
26        })
27        .catch(error => {
28          reject(error);
29          this.activeCount--;
30          this.process();
31        });
32    }
33  }
34}
35
36// Usage: 10 parallel renders on Pro plan
37const queue = new ParallelQueue(10);
38
39// Add 100 renders - they'll process 10 at a time
40for (const design of designs) {
41  queue.add({ mockup_uuid, smart_objects: [{ uuid: soId, asset: { url: design } }] })
42    .then(result => console.log('Done:', result))
43    .catch(err => console.error('Failed:', err));
44}

Error Types & Handling

Code	Meaning	Action
200	Success	Process result
400	Bad request	Fix payload, don't retry
401	Unauthorized	Check API key
404	Not found	Check mockup UUID
429	Parallel limit reached	Retry with backoff
500	Server error	Retry with backoff

Don't Retry Everything

Only retry 429 and 5xx errors. Client errors like 400 and 401 won't succeed on retry - fix the underlying issue instead.

Monitoring & Metrics

Track these metrics to optimize your API usage:

Active requests - Stay below your parallel limit

429 frequency - High frequency = need to upgrade or queue better

Latency - Average response time

Error rate - Non-429 errors indicate code issues

Best Practice

Use the x-concurrent-remaining header proactively. If it's getting low, wait for active requests to complete before sending more.

Related Resources

Render API Reference

Complete endpoint documentation

View Plans

Compare parallel limits by tier

Scaling Guide

High-volume best practices

Status Page

Check API health

Understanding Parallel Limits

SudoMock uses parallel limits to ensure fair usage and consistent performance. These limits determine how many simultaneous requests you can have in-flight at once:

Plan	Parallel Renders	Parallel Uploads
Free	1	1
Starter	3	2
Pro	10	5
Scale	25	10

Response Headers

Every API response includes parallel limit headers:

x-concurrent-limit - Your parallel limit
x-concurrent-remaining - Available slots
Retry-After - Seconds to wait (only on 429 responses)

Handling 429 Errors

When you exceed parallel limits, the API returns 429 Parallel Limit Reached. Here's how to handle it properly:

Basic retry with backoff

javascript

1async function renderWithRetry(payload, maxRetries = 3) {
2  for (let attempt = 0; attempt < maxRetries; attempt++) {
3    const response = await fetch('https://api.sudomock.com/api/v1/renders', {
4      method: 'POST',
5      headers: {
6        'X-API-KEY': API_KEY,
7        'Content-Type': 'application/json'
8      },
9      body: JSON.stringify(payload)
10    });
11
12    if (response.ok) {
13      return response.json();
14    }
15
16    if (response.status === 429) {
17      // Get retry delay from header, or use short backoff
18      const retryAfter = response.headers.get('Retry-After');
19      const delay = retryAfter
20        ? parseInt(retryAfter) * 1000
21        : Math.pow(2, attempt) * 1000;
22
23      console.log(`Parallel limit reached. Retrying in \${delay}ms...`);
24      await sleep(delay);
25      continue;
26    }
27
28    // Other errors - don't retry
29    throw new Error(`API error: \${response.status}`);
30  }
31
32  throw new Error('Max retries exceeded');
33}
34
35function sleep(ms) {
36  return new Promise(resolve => setTimeout(resolve, ms));
37}

Exponential Backoff

For retry logic, exponential backoff prevents overwhelming the API. The delay doubles with each retry attempt:

Retry 1

First attempt

Retry 2

Second attempt

Retry 3

Third attempt

Retry 4

Fourth attempt

Exponential backoff with jitter

javascript

1function getBackoffDelay(attempt, baseDelay = 1000) {
2  // Exponential: 1s, 2s, 4s, 8s...
3  const exponentialDelay = Math.pow(2, attempt) * baseDelay;
4
5  // Add jitter (0-25% random) to prevent thundering herd
6  const jitter = exponentialDelay * Math.random() * 0.25;
7
8  // Cap at 30 seconds
9  return Math.min(exponentialDelay + jitter, 30000);
10}

Why Jitter?

When multiple clients hit limits simultaneously, they all retry at the same time - causing another limit breach. Adding random jitter spreads out retries.

Parallel Processing Strategy

For high-volume workloads, process requests in parallel up to your plan's limit:

Parallel worker pool

javascript

1class ParallelQueue {
2  constructor(parallelLimit) {
3    this.queue = [];
4    this.activeCount = 0;
5    this.parallelLimit = parallelLimit;
6    this.results = [];
7  }
8
9  async add(payload) {
10    return new Promise((resolve, reject) => {
11      this.queue.push({ payload, resolve, reject });
12      this.process();
13    });
14  }
15
16  async process() {
17    while (this.queue.length > 0 && this.activeCount < this.parallelLimit) {
18      const { payload, resolve, reject } = this.queue.shift();
19      this.activeCount++;
20
21      renderWithRetry(payload)
22        .then(result => {
23          resolve(result);
24          this.activeCount--;
25          this.process(); // Process next in queue
26        })
27        .catch(error => {
28          reject(error);
29          this.activeCount--;
30          this.process();
31        });
32    }
33  }
34}
35
36// Usage: 10 parallel renders on Pro plan
37const queue = new ParallelQueue(10);
38
39// Add 100 renders - they'll process 10 at a time
40for (const design of designs) {
41  queue.add({ mockup_uuid, smart_objects: [{ uuid: soId, asset: { url: design } }] })
42    .then(result => console.log('Done:', result))
43    .catch(err => console.error('Failed:', err));
44}

Error Types & Handling

Code	Meaning	Action
200	Success	Process result
400	Bad request	Fix payload, don't retry
401	Unauthorized	Check API key
404	Not found	Check mockup UUID
429	Parallel limit reached	Retry with backoff
500	Server error	Retry with backoff

Don't Retry Everything

Only retry 429 and 5xx errors. Client errors like 400 and 401 won't succeed on retry - fix the underlying issue instead.

Monitoring & Metrics

Track these metrics to optimize your API usage:

Active requests - Stay below your parallel limit

429 frequency - High frequency = need to upgrade or queue better

Latency - Average response time

Error rate - Non-429 errors indicate code issues

Best Practice

Use the x-concurrent-remaining header proactively. If it's getting low, wait for active requests to complete before sending more.

Related Resources

Render API Reference

Complete endpoint documentation

View Plans

Compare parallel limits by tier

Scaling Guide

High-volume best practices

Status Page

Check API health

API Integration Best Practices

TL;DR

Key Takeaways:

Understanding Parallel Limits

Handling 429 Errors

Exponential Backoff

Parallel Processing Strategy

Error Types & Handling

Monitoring & Metrics

Related Resources

Render API Reference

View Plans

Scaling Guide

Status Page

Frequently Asked Questions

Related Articles

SudoMock Now Works with Claude, Cursor, ChatGPT, and Any MCP-Compatible AI Tool

Understanding Mockup API Data Models: A Technical Guide

Explore by Use Case

Your own PSD, rendered via API

API Integration Best Practices

TL;DR

Key Takeaways:

Understanding Parallel Limits

Handling 429 Errors

Exponential Backoff

Parallel Processing Strategy

Error Types & Handling

Monitoring & Metrics

Related Resources

Render API Reference

View Plans

Scaling Guide

Status Page

Frequently Asked Questions

Related Articles

SudoMock Now Works with Claude, Cursor, ChatGPT, and Any MCP-Compatible AI Tool

Understanding Mockup API Data Models: A Technical Guide

Explore by Use Case

Your own PSD, rendered via API