Skip to main content

​
API Errors

Understanding and handling API errors correctly ensures your integration is robust and user-friendly.

​
Error Response Format

All errors follow a consistent structure: 
{
  "version": "1.0",
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

​
Error Codes

​
INVALID_INPUT

The request body or parameters are invalid. HTTP Status: 400 Causes:
  • Missing required fields
  • Invalid data types
  • Malformed JSON
Example: 
{
  "version": "1.0",
  "error": {
    "code": "INVALID_INPUT",
    "message": "Both techA and techB are required."
  }
}
Solution: Ensure all required fields are present and correctly formatted.

​
RATE_LIMIT_EXCEEDED

Request exceeds rate limit for the endpoint. HTTP Status: 429 Causes:
  • Too many requests in the rate limit window
  • Multiple clients sharing the same IP
Example: 
{
  "version": "1.0",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": "Reset at 2025-01-15T10:31:00Z"
  }
}
Headers: 
Retry-After: 45
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2025-01-15T10:31:00Z
Solution: Wait until the X-RateLimit-Reset time or Retry-After seconds have passed. See Rate Limits for handling strategies.

​
INTERNAL_ERROR

An unexpected server error occurred. HTTP Status: 500 Causes:
  • Temporary server issues
  • Database connection problems
  • Unexpected data conditions
Example: 
{
  "version": "1.0",
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An error occurred while checking compatibility",
    "details": "Specific error message for debugging"
  }
}
Solution: Retry the request after a delay. If the issue persists, contact support.

​
NOT_FOUND

Requested resource does not exist. HTTP Status: 404 Causes:
  • Invalid endpoint path
  • Removed compatibility data
Example: 
{
  "version": "1.0",
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found."
  }
}
Solution: Verify the endpoint URL and technology names are correct.

​
NO_TECH_DETECTED

Scan request found no recognizable technologies. HTTP Status: 400 Causes:
  • No packages in dependencies
  • Unrecognized package names
  • Empty package.json
Example: 
{
  "version": "1.0",
  "error": {
    "code": "NO_TECH_DETECTED",
    "message": "No recognized technologies found in dependencies",
    "details": "Ensure you have valid packages in your package.json"
  }
}
Solution: Verify your dependencies array or package.json contains valid package names.

​
HTTP Status Codes

StatusMeaningAction
200SuccessProcess the response
400Bad RequestFix request parameters
404Not FoundVerify endpoint URL
429Rate LimitedWait and retry
500Server ErrorRetry with backoff

​
Error Handling Best Practices

​
1. Always Check HTTP Status

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  // Handle error based on status code
  switch (response.status) {
    case 400:
      console.error('Invalid input:', error.error.message);
      break;
    case 429:
      console.error('Rate limited. Retry at:', error.error.details);
      break;
    default:
      console.error('Unexpected error:', error.error.message);
  }
  return;
}

// Process successful response
const data = await response.json();

​
2. Implement Retry Logic

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

      if (response.ok || response.status === 400) {
        // Success or client error - don't retry
        return response;
      }

      if (response.status === 429) {
        // Rate limited - wait for reset time
        const resetAt = response.headers.get('X-RateLimit-Reset');
        const waitMs = new Date(resetAt) - Date.now() + 1000;
        await new Promise(resolve => setTimeout(resolve, waitMs));
        continue;
      }

      if (response.status >= 500) {
        // Server error - exponential backoff
        const waitMs = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, waitMs));
        continue;
      }

    } catch (error) {
      if (i === maxRetries - 1) throw error;
      // Network error - exponential backoff
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
    }
  }

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

​
3. Log Errors Contextually

function logApiError(endpoint, error, context = {}) {
  console.error({
    timestamp: new Date().toISOString(),
    endpoint,
    errorCode: error.error?.code,
    message: error.error?.message,
    ...context
  });
}

// Usage
try {
  const data = await checkCompatibility('nextjs', 'prisma');
} catch (error) {
  logApiError('/api/v1/check', error, {
    techA: 'nextjs',
    techB: 'prisma'
  });
}

​
4. Provide User-Friendly Messages

function getErrorMessage(error, context = {}) {
  switch (error.error?.code) {
    case 'INVALID_INPUT':
      return 'Please check your input and try again.';
    case 'RATE_LIMIT_EXCEEDED':
      return 'Too many requests. Please wait a moment.';
    case 'INTERNAL_ERROR':
      return 'Service temporarily unavailable. Please try again.';
    default:
      return 'An unexpected error occurred.';
  }
}

​
Testing Error Handling

​
Test Scenarios

ScenarioHow to TestExpected Behavior
Invalid inputSend empty techA/techBReturns 400 with INVALID_INPUT
Rate limitMake 60+ requests in a minuteReturns 429 with RATE_LIMIT_EXCEEDED
Unknown techUse non-existent technology namesReturns 200 with status=“unknown”
Server error(Contact support to simulate)Returns 500 with INTERNAL_ERROR

​
Example Test

async function testInvalidInput() {
  const response = await fetch('https://devradar.dev/api/v1/check', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ techA: '', techB: '' })
  });

  console.assert(response.status === 400, 'Expected 400 status');
  const error = await response.json();
  console.assert(error.error.code === 'INVALID_INPUT', 'Expected INVALID_INPUT');
  console.log('Test passed!');
}

​
Getting Help

​
Persistent Errors

If you encounter errors consistently:
  1. Check Status Page - Verify service is operational
  2. Review Your Code - Ensure proper error handling
  3. Check Rate Limits - Verify you’re within limits
  4. Contact Support - Include error code and request details

​
Support Contact

​
What’s Next

Need help? Contact Support →