Error Handling

Learn how to handle errors returned by the DevUtils API. All errors follow a consistent format to help you diagnose and resolve issues quickly.

HTTP Status Codes

The DevUtils API uses conventional HTTP status codes to indicate the success or failure of requests:

Status Code	Name	Description
200	Success	Request completed successfully
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Invalid or missing API key
403	Forbidden	API key does not have permission for this action
429	Rate Limited	Too many requests. Slow down and retry
500	Internal Error	Something went wrong on our end

Error Response Format

All error responses include a consistent JSON structure:

Error Responsejson

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401
  }
}

Common Errors

invalid_api_key

The API key is missing, invalid, or has been revoked.

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401
  }
}

rate_limit_exceeded

You've exceeded your plan's rate limit.

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "status": 429,
    "retry_after": 60
  }
}

invalid_url

The provided URL is malformed or inaccessible.

{
  "success": false,
  "error": {
    "code": "invalid_url",
    "message": "The URL provided is invalid or could not be accessed.",
    "status": 400
  }
}

Handling Errors

Here is an example of how to handle errors in your application:

JavaScript Error Handlingjavascript

async function captureScreenshot(url) {
  try {
    const response = await fetch('https://api.devutils.io/v1/screenshot', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.DEVUTILS_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ url })
    });

    const data = await response.json();

    if (!data.success) {
      // Handle specific error codes
      switch (data.error.code) {
        case 'rate_limit_exceeded':
          // Wait and retry
          await new Promise(r => setTimeout(r, data.error.retry_after * 1000));
          return captureScreenshot(url);
        case 'invalid_api_key':
          throw new Error('Please check your API key');
        default:
          throw new Error(data.error.message);
      }
    }

    return data.data;
  } catch (error) {
    console.error('Screenshot failed:', error);
    throw error;
  }
}