Authentication Errors
These errors relate to logging in, API keys, and session management.
| Error Message | Cause | Solution |
|---|---|---|
| "Invalid API key" | The API key in your request doesn't match any active key | Check the key is correct, hasn't been deleted, and is being sent in the Authorization: Bearer header |
| "API key expired" | The key was manually revoked or deleted | Generate a new key from Settings → API Keys |
| "Session expired" | Your login session has timed out | Log out and log back in. Sessions expire after 24 hours of inactivity |
| "Unauthorized" | Your user role doesn't have permission for this action | Check your role (Settings → Team). Ask an Admin or Super Admin to grant access |
| "Account suspended" | Your account has been suspended (usually billing-related) | Contact support or check Settings → Billing for payment issues |
| "Too many login attempts" | Multiple failed login attempts triggered a lockout | Wait 15 minutes, then try again. Use "Forgot Password" if needed |
Integration Errors
These errors occur when DealOracle communicates with connected ad platforms.
| Error Message | Cause | Solution |
|---|---|---|
| "Pixel not found" | The pixel or conversion ID configured in DealOracle doesn't exist on the ad platform | Go to the integration settings and verify the pixel/conversion ID matches what's in your ad platform |
| "Invalid access token" | The OAuth token has expired or been revoked | Disconnect and reconnect the integration to get a fresh token |
| "Event rejected" | The ad platform rejected the conversion event | Click the failed event in the lead's event stream to see the detailed rejection reason from the platform |
| "Permission denied" | Your ad platform account no longer has the required permissions | Check your role on the ad platform. Restore permissions, then reconnect the integration |
| "Platform unavailable" | The ad platform's API is experiencing an outage | Check the platform's status page. DealOracle will auto-retry when the platform comes back online |
| "Event name not recognized" | The conversion event name doesn't match any configured event on the ad platform | Check your event mapping and ensure the event name exactly matches what's configured in the ad platform |
| "Duplicate event" | The same conversion was already sent for this lead | No action needed — the platform ignored the duplicate to prevent double-counting |
Data Errors
These errors relate to lead data, imports, and webhooks.
| Error Message | Cause | Solution |
|---|---|---|
| "Duplicate lead" | A lead with this email address already exists in the current client account | Use the existing lead record, or merge the data manually. The webhook returns 409 with the existing lead's ID |
| "Required field missing" | A CSV import row or webhook payload is missing name or email | Check your data source. Both name and email are required fields for lead creation |
| "Invalid email format" | The email address is malformed | Verify the email address follows standard format (e.g., [email protected]). Common issues: extra spaces, missing @ symbol, missing domain |
| "Invalid phone format" | The phone number doesn't match expected format | Use E.164 format (e.g., +15551234567). Include country code, digits only (no dashes or spaces) |
| "Rate limit exceeded" | Too many API requests in a short time period | Wait for the period specified in the Retry-After header, then retry. Consider spacing out requests |
| "Import failed: row X" | A specific row in a CSV import couldn't be processed | Check row X in your CSV for missing required fields, invalid email format, or encoding issues |
| "File too large" | CSV import file exceeds the maximum size | Split your CSV into smaller files (max 10,000 rows per import) and import them separately |
| "Client not found" | The API key is associated with a client account that no longer exists | Generate a new API key for the correct client account from Settings → API Keys |
#errors#faq#troubleshooting