Error Handling

The Dupify API uses standard HTTP response codes and returns detailed error messages in JSON format to help you diagnose and fix issues quickly.

Error Response Format

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable error description",
    "details": { ... }  // Optional additional context
  }
}

HTTP Status Codes

Code	Meaning
200 OK	Request succeeded
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Valid key but insufficient permissions or quota exceeded
404 Not Found	Requested resource doesn't exist
422 Unprocessable Entity	Image could not be processed
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server-side error (retry with backoff)
503 Service Unavailable	Service temporarily down (retry later)

Common Error Codes

Authentication Errors (401)

missing_api_key

No API key provided. Include your key in the X-API-Key header.

invalid_api_key

The provided API key doesn't exist or has been revoked. Check your dashboard for valid keys.

expired_api_key

The API key has expired. Generate a new key from your dashboard.

Permission Errors (403)

insufficient_scope

Your API key doesn't have the required scope for this endpoint. Create a new key with the needed scopes.

quota_exceeded

You've exceeded your monthly API call quota. Upgrade your plan or wait for the next billing period.

Validation Errors (400)

missing_parameter

A required parameter is missing. Check the details field for which parameter.

invalid_parameter

A parameter has an invalid value. Check the details field for specifics.

invalid_image_url

The provided image URL is malformed or inaccessible.

invalid_base64

The provided base64 string is not valid base64-encoded image data.

Processing Errors (422)

image_fetch_failed

Could not download the image from the provided URL. Check that the URL is publicly accessible.

unsupported_format

The image format is not supported. We accept JPEG, PNG, WebP, and GIF.

image_too_large

The image exceeds the maximum size of 10MB. Resize or compress the image before uploading.

processing_failed

The image could not be processed. This may happen with corrupted or very unusual images.

Rate Limit Errors (429)

rate_limit_exceeded

You've exceeded your rate limit. Wait for the time specified in retry_after before retrying.

Retry Strategies

Exponential Backoff

For 429 and 5xx errors, implement exponential backoff:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) return response.json();

    if (response.status === 429 || response.status >= 500) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter
        ? parseInt(retryAfter) * 1000
        : Math.pow(2, attempt) * 1000;

      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    // Don't retry 4xx errors (except 429)
    throw new Error(`API error: ${response.status}`);
  }

  throw new Error('Max retries exceeded');
}

When to Retry

Error	Retry?	Strategy
400	No	Fix the request and resend
401	No	Check your API key
403	No	Check permissions or upgrade plan
422	No	Fix the image issue
429	Yes	Wait for retry_after seconds
500	Yes	Exponential backoff
503	Yes	Wait and retry

Debugging Tips

Check the full error response — The details field often contains specific information about what went wrong
Verify your API key — Test with a simple request to confirm your key is working
Check image accessibility — Ensure your image URLs are publicly accessible (no auth required)
Monitor your usage — Use the dashboard to track your API calls and remaining quota
Check our status page — For 5xx errors, verify the service is operational

Still stuck?

Email us at support@dupifyapp.com with your request ID (from the response headers) and we'll help you debug.

← Rate Limits Back to Overview