Error Handling

Comprehensive guide to handling errors in the AIDP API.

Error Response Format

All API errors follow a consistent format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional context"
  },
  "requestId": "req_abc123"
}

---

HTTP Status Codes

2xx Success

• 200 OK: Request successful

• 201 Created: Resource created successfully

4xx Client Errors

• 400 Bad Request: Invalid request parameters

• 401 Unauthorized: Missing or invalid API key

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Resource doesn't exist

• 429 Too Many Requests: Rate limit exceeded

5xx Server Errors

• 500 Internal Server Error: Server-side error

• 503 Service Unavailable: Temporary service disruption

---

Common Errors

Authentication Errors

401 Unauthorized

{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}

Solution: Check your API key is correct and active.

Validation Errors

400 Bad Request

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "query": "Query is required",
    "location.lat": "Must be between -90 and 90"
  }
}

Solution: Fix the invalid fields listed in details.

Rate Limit Errors

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 3600
}

Solution: Wait retryAfter seconds before retrying.

Not Found Errors

404 Not Found

{
  "error": "Business not found",
  "code": "BUSINESS_NOT_FOUND",
  "details": {
    "businessId": "biz_invalid123"
  }
}

Solution: Verify the resource ID is correct.

---

Error Handling Best Practices

1. Always Check Status Codes

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  throw new APIError(error.error, error.code, response.status);
}

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.status === 429) {
        const retryAfter = response.headers.get('X-RateLimit-Retry-After');
        await sleep(retryAfter * 1000);
        continue;
      }

      if (response.status >= 500) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }

      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

3. Log Errors with Request IDs

try {
  const data = await apiCall();
} catch (error) {
  console.error('API Error:', {
    message: error.message,
    code: error.code,
    requestId: error.requestId,
    timestamp: new Date().toISOString(),
  });
}

4. Provide User-Friendly Messages

function getUserMessage(error) {
  switch (error.code) {
    case 'RATE_LIMIT_EXCEEDED':
      return 'Too many requests. Please try again in a few minutes.';
    case 'VALIDATION_ERROR':
      return 'Please check your input and try again.';
    case 'BUSINESS_NOT_FOUND':
      return 'Business not found. Please verify the ID.';
    default:
      return 'An error occurred. Please try again later.';
  }
}

---

Error Codes Reference

Code	Description	Action
INVALID_API_KEY	API key is invalid or missing	Check API key
RATE_LIMIT_EXCEEDED	Too many requests	Wait and retry
VALIDATION_ERROR	Invalid request parameters	Fix parameters
BUSINESS_NOT_FOUND	Business doesn't exist	Verify ID
UNAUTHORIZED	Insufficient permissions	Check permissions
INTERNAL_ERROR	Server error	Retry or contact support

---

Need Help?

• 📧 Email: [e-mail]

• 📚 Documentation: docs.aidp.dev/errors