Skip to main content

​
Common Error Codes

The MDB Enrichment API uses standard HTTP status codes and provides detailed error responses to help you troubleshoot issues quickly.

​
Error Response Format

All errors follow a consistent JSON structure: 
{
  "error": "error_type",
  "message": "Human-readable error description",
  "code": "MDB_ERROR_CODE",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "details": {
    // Additional context when available
  }
}

​
Authentication Errors (401)

​
Invalid API Key

{
  "error": "unauthorized",
  "message": "Invalid or missing API key",
  "code": "AUTH_001",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV"
}
Solution: Verify your API key is correct and included in the x-api-key header.

​
Expired API Key

{
  "error": "unauthorized",
  "message": "API key has expired",
  "code": "AUTH_002",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAW"
}
Solution: Generate a new API key from your MDB Dashboard.

​
Malformed API Key

{
  "error": "unauthorized",
  "message": "API key format is invalid",
  "code": "AUTH_003",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX"
}
Solution: Ensure your API key is properly formatted and not corrupted.

​
Authorization Errors (403)

​
Insufficient Permissions

{
  "error": "forbidden",
  "message": "Your API key does not have permission to access this endpoint",
  "code": "AUTH_101",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
  "details": {
    "required_permission": "email_validation",
    "your_permissions": ["ip_lookup", "linkedin_scraping"]
  }
}
Solution: Contact support to upgrade your API permissions or use an endpoint you have access to.

​
Account Suspended

{
  "error": "forbidden",
  "message": "Your account has been suspended",
  "code": "AUTH_102",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAZ"
}
Solution: Contact support to resolve account issues.

​
Billing & Usage Errors (402, 429)

​
Billing Limit Exceeded

{
  "error": "payment_required",
  "message": "Monthly billing limit exceeded",
  "code": "BILLING_001",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB0",
  "details": {
    "current_usage": 15000,
    "monthly_limit": 10000,
    "reset_date": "2024-02-01T00:00:00Z"
  }
}
Solution: Upgrade your plan or wait until your billing cycle resets.

​
Rate Limit Exceeded

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests, please slow down",
  "code": "RATE_001",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB1",
  "details": {
    "limit": 1000,
    "window": "1 minute",
    "retry_after": 45
  }
}
Solution: Implement exponential backoff and respect the retry_after value.

​
Request Errors (400)

​
Invalid Request Format

{
  "error": "bad_request",
  "message": "Request body must be valid JSON",
  "code": "REQ_001",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB2"
}
Solution: Ensure your request body is properly formatted JSON.

​
Missing Required Parameters

{
  "error": "bad_request",
  "message": "Missing required parameter",
  "code": "REQ_002",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB3",
  "details": {
    "missing_parameter": "email",
    "parameter_type": "string"
  }
}
Solution: Include all required parameters as specified in the endpoint documentation.

​
Invalid Parameter Value

{
  "error": "bad_request",
  "message": "Invalid parameter value",
  "code": "REQ_003",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB4",
  "details": {
    "parameter": "email",
    "value": "not-an-email",
    "expected": "Valid email address format"
  }
}
Solution: Provide valid values according to the parameter requirements.

​
Service Errors (404, 500)

​
Endpoint Not Found

{
  "error": "not_found",
  "message": "The requested endpoint does not exist",
  "code": "API_404",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB5"
}
Solution: Check the endpoint URL and ensure you’re using the correct API version.

​
Internal Server Error

{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "code": "SRV_001",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB6"
}
Solution: Retry the request. If the error persists, contact support with the request_id.

​
Service Temporarily Unavailable

{
  "error": "service_unavailable",
  "message": "Service is temporarily unavailable for maintenance",
  "code": "SRV_503",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FB7",
  "details": {
    "retry_after": 300,
    "maintenance_window": "2024-01-20T02:00:00Z to 2024-01-20T04:00:00Z"
  }
}
Solution: Wait for the maintenance window to complete and retry your request.

​
Best Practices for Error Handling

​
1. Always Check Status Codes

if (response.status >= 400) {
  const error = await response.json();
  console.error(`API Error ${error.code}: ${error.message}`);
}

​
2. Implement Retry Logic

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      if (response.status === 429) {
        const error = await response.json();
        await new Promise(resolve => setTimeout(resolve, error.details.retry_after * 1000));
        continue;
      }
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

​
3. Log Error Details

Always log the error code and request ID for debugging: 
console.error(`Error ${error.code}: ${error.message}`, {
  requestId: error.request_id,
  timestamp: new Date().toISOString()
});

​
Getting Help

If you encounter errors not listed here or need assistance:
  • Check your dashboard at mdb.tools for account status
  • Contact support at hello@midbound.ai
  • Include error codes and request IDs in your support requests for faster resolution