Error Handling

Best practices for handling API errors and implementing robust error recovery.

HTTP Status Codes

The DriveDecision API uses standard HTTP status codes to indicate success or failure:

Code	Status	Description
200	OK	Request successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	API key lacks required permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Error Response Format

Error responses include a JSON body with details:

Error response

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid year format. Expected YYYY.",
    "field": "year",
    "documentation_url": "https://docs.drivedecision.com/errors/INVALID_PARAMETER"
  }
}

Handling Errors in Code

Example of proper error handling in JavaScript:

Error handling example

async function getVehicleData(make, model, year) {
  try {
    const response = await fetch(
      `https://api.drivedecision.com/v1/vehicles/${make}/${model}/${year}`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
        },
      }
    );

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 401:
          throw new Error('Invalid API key. Check your credentials.');
        case 404:
          throw new Error(`Vehicle not found: ${make} ${model} ${year}`);
        case 429:
          // Implement retry with exponential backoff
          throw new Error('Rate limit exceeded. Retry after delay.');
        default:
          throw new Error(error.error?.message || 'Unknown error');
      }
    }

    return await response.json();
  } catch (error) {
    console.error('API Error:', error.message);
    throw error;
  }
}

Retry Strategy

For transient errors (429, 5xx), implement exponential backoff:

Retry with exponential backoff

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

      if (response.status === 429 || response.status >= 500) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

Rate Limiting

Rate limits vary by plan. Check the X-RateLimit-* headers in responses:

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 999

X-RateLimit-Reset: 1704067200