Error Codes

Complete reference of all error codes returned by the DorkList API and how to handle them.

Error Response Format

When an error occurs, the API returns a JSON response with success: false and an error object containing the code and message:

json

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}

Authentication Errors

These errors occur when there's a problem with your API key or authentication.

Code	Status	Description	Solution
MISSING_AUTH	401	No Authorization header	Add the Authorization header with your API key
INVALID_FORMAT	401	Key doesn't match dk_* format	Ensure key starts with "dk_" prefix
INVALID_KEY	401	API key not found	Check your key or generate a new one
KEY_INACTIVE	401	API key has been deactivated	Reactivate or create a new key in settings
KEY_EXPIRED	401	API key has expired	Generate a new API key
USER_NOT_FOUND	401	User account doesn't exist	Account may have been deleted
NOT_PRO_USER	403	Pro subscription required	Upgrade to Pro to use the API

Rate Limiting Errors

Code	Status	Description	Solution
RATE_LIMITED	429	Daily rate limit exceeded	Wait until midnight UTC or check X-RateLimit-Reset header

Request Errors

Code	Status	Description	Solution
MISSING_PARAMETER	400	Required parameter missing	Check required parameters in the docs
INVALID_PARAMETER	400	Parameter value is invalid	Check parameter types and constraints
NOT_FOUND	404	Resource not found	Verify the ID or resource exists
METHOD_NOT_ALLOWED	405	HTTP method not supported	Use GET for all endpoints

Server Errors

Code	Status	Description	Solution
INTERNAL_ERROR	500	Server error occurred	Retry request or contact support
SERVICE_UNAVAILABLE	503	Service temporarily unavailable	Wait and retry with exponential backoff

Error Handling Example

Here's how to properly handle errors in your code:

javascript

async function fetchDorks() {
  try {
    const response = await fetch('https://dorklist.com/api/v1/dorks', {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });
    const data = await response.json();
    if (!data.success) {
      // Handle API errors
      switch (data.error.code) {
        case 'RATE_LIMITED':
          const resetTime = response.headers.get('X-RateLimit-Reset');
          console.log(`Rate limited. Reset at: ${new Date(resetTime * 1000)}`);
          break;
        case 'INVALID_KEY':
        case 'KEY_EXPIRED':
          console.error('API key issue - please check your key');
          break;
        case 'NOT_PRO_USER':
          console.error('Pro subscription required for API access');
          break;
        default:
          console.error(`API Error: ${data.error.message}`);
      }
      return null;
    }
    return data.data.dorks;
  } catch (error) {
    // Handle network errors
    console.error('Network error:', error.message);
    return null;
  }
}