# Troubleshooting

Quick solutions to common problems. Can't find your issue? [Contact support](mailto:support@bentonow.com) or ask in [Discord](https://discord.com/invite/ssXXFRmt5F).

---

## API Issues {{ id: 'api-issues' }}

### 401 Unauthorized

**Symptoms**: API returns `401 Unauthorized` or `{"error": "Unauthorized"}`

**Common Causes & Solutions**:

| Cause                     | Solution                                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| Wrong API keys            | Double-check you're using the correct publishable key and secret key from Settings → API Keys     |
| Missing site_uuid         | Add `?site_uuid=YOUR_SITE_UUID` to your API URL                                                   |
| Wrong site_uuid           | Each site has a unique UUID - make sure you're using the right one                                |
| Incorrect Base64 encoding | Encode `publishable_key:secret_key` (with the colon) - see [Authentication](/docs/authentication) |
| Keys from different site  | Your keys and site_uuid must be from the same site                                                |

**Debug Steps**:

```bash
# Test your credentials with a simple GET request
curl -X GET 'https://app.bentonow.com/api/v1/fetch/tags?site_uuid=YOUR_SITE_UUID' \
  -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS' \
  -H 'User-Agent: Debug/1.0'
```

---

### Getting HTML Instead of JSON

**Symptoms**: API returns HTML content, often a Cloudflare page, instead of JSON

**Cause**: Missing or invalid `User-Agent` header

**Solution**: Add a User-Agent header to every request:

```bash
-H 'User-Agent: YourAppName/1.0'
```


> 🚨 **Important**
> This is the most common API issue we see. The User-Agent header is **required** - Cloudflare blocks requests without it.


---

### 429 Too Many Requests

**Symptoms**: API returns `429 Too Many Requests`

**Cause**: You've exceeded the rate limit (100 requests/minute for most endpoints)

**Solutions**:

- Add delays between requests
- Batch multiple operations into single requests where possible
- Use webhooks instead of polling
- Contact support if you need higher limits

---

### Request Timing Out

**Symptoms**: Requests hang or time out after 30+ seconds

**Common Causes**:

- Large batch imports (use smaller batches of 100-500)
- Network issues on your end
- Rarely, Bento service issues (check [status.bentonow.com](https://status.bentonow.com))

**Solutions**:

- Break large imports into smaller batches
- Add timeout handling to your code
- Implement retry logic with exponential backoff

---

## Deliverability Issues {{ id: 'deliverability-issues' }}

### Emails Going to Spam

**Step 1: Check your DNS records**

- Go to Deliverability → DNS Records
- Click "Validate DNS Records"
- All records should show as valid (green checkmarks)

**Step 2: Check your domain reputation**

- Use [Google Postmaster Tools](https://postmaster.google.com/)
- Check for any domain or IP reputation issues

**Step 3: Review your content**

- Avoid spam trigger words (FREE, URGENT, ACT NOW)
- Don't use URL shorteners
- Ensure text-to-image ratio is reasonable
- Include a clear unsubscribe link (Bento adds this automatically)

**Step 4: Review your sending patterns**

- Are you sending to a clean list?
- Have you warmed up your domain? See [Warmup Guide](/docs/deliverability/warmup)
- Are you getting high bounce rates or spam complaints?


> If you recently set up DNS records, it can take 24-48 hours for reputation to improve.


---

### Low Open Rates

**Normal**: 20-40% for engaged lists  
**Warning**: Below 15%

**If open rates suddenly dropped:**

1. Check DNS records haven't been deleted (we've seen this happen!)
2. Verify no changes to your sending domain
3. Check if emails are landing in spam (send test to yourself)

**If open rates are consistently low:**

1. Clean your list - remove subscribers who haven't opened in 6+ months
2. Re-engage inactive subscribers before removing them
3. Review subject lines - are they compelling?
4. Check send times - experiment with different times

---

### High Bounce Rates

**Normal**: Under 2%  
**Warning**: Above 5%

**For imported lists:**

- Clean your list before importing
- Remove addresses that bounced on previous providers
- Don't import purchased lists

**For ongoing sends:**

- Bento automatically removes hard bounces
- Check for typos in email collection forms
- Consider double opt-in for new signups

See [Bounce Guide](/docs/deliverability/bounces) for detailed information.

---

## Integration Issues {{ id: 'integration-issues' }}

### Webhooks Not Firing

**Check these first:**

1. **URL is accessible**: Your webhook URL must be publicly accessible (not localhost)
2. **URL returns 200**: Bento expects a 200 response within 10 seconds
3. **SSL is valid**: If using HTTPS, your certificate must be valid

**Debug steps:**

1. Check webhook logs in Bento (Settings → Webhooks)
2. Use a tool like [webhook.site](https://webhook.site) to test
3. Check your server logs for incoming requests

---

### Shopify Integration Not Syncing

**Common issues:**

| Problem                     | Solution                                               |
| --------------------------- | ------------------------------------------------------ |
| Orders not appearing        | Wait 5-10 minutes - there's a slight delay             |
| Missing customer data       | Ensure customer created account at checkout            |
| Events not triggering flows | Check your flow trigger matches the event name exactly |

**Re-sync steps:**

1. Go to Apps → Shopify
2. Click "Disconnect"
3. Reconnect the integration
4. Historical data won't sync, but new events will

---

### Zapier/Make.com Connection Failing

**For Zapier:**

1. Reconnect your Bento account in Zapier
2. Make sure you're using API keys, not OAuth
3. Check your Zap's error logs

**For Make.com:**

1. Verify API keys are correct
2. Check that site_uuid is included
3. Review scenario execution logs

---

## DNS Issues {{ id: 'dns-issues' }}

### DNS Records Not Validating

**Common causes:**

| Issue                      | Solution                                                          |
| -------------------------- | ----------------------------------------------------------------- |
| Records not propagated yet | Wait 24-48 hours (sometimes up to 72)                             |
| Wrong record type          | Make sure you're using the exact type (CNAME vs TXT)              |
| Extra spaces               | Remove any trailing spaces in record values                       |
| Proxy enabled              | For Cloudflare, disable the orange cloud (proxy) for mail records |
| Wrong subdomain            | Check you're using the exact subdomain specified                  |

**Check propagation:**
Use [dnschecker.org](https://dnschecker.org) to verify your records are visible globally.

---

### DKIM Validation Failing

**Most common cause**: The DKIM record value is too long and got truncated by your DNS provider.

**Solution**:

- Some providers require you to split long TXT records
- Check with your DNS provider's documentation
- See our [DNS provider guides](/docs/dns) for specific instructions

---

### Link Branding Not Working

**Symptoms**: Links in emails show `clicks.bentonow.com` instead of your domain

**Causes**:

1. CNAME record not set up
2. CNAME not validated in Bento
3. SSL certificate not provisioned (automatic, but can take a few minutes)

**Solution**:

1. Go to Deliverability → DNS Records
2. Add the link branding CNAME record
3. Click "Validate" and wait for green checkmark

---

## Dashboard Issues {{ id: 'dashboard-issues' }}

### Subscriber Count Seems Wrong

**Bento counts unique subscribers**, not events or form submissions. The same email address is only counted once.

If counts seem off:

- Check if you're looking at the right site
- Segment filters may be excluding subscribers
- Recently imported subscribers may still be processing

---

### Events Not Appearing on Profile

**Check these:**

1. Event was sent to the correct email address
2. The site_uuid matches the site you're viewing
3. Events can take up to 30 seconds to appear during high load

**Test with a manual event:**

```bash
curl -X POST 'https://app.bentonow.com/api/v1/batch/events?site_uuid=YOUR_SITE_UUID' \
  -H 'Authorization: Basic YOUR_CREDENTIALS' \
  -H 'User-Agent: Debug/1.0' \
  -H 'Content-Type: application/json' \
  -d '{"events": [{"type": "test_event", "email": "YOUR_EMAIL"}]}'
```

---

### Flow Not Triggering

**Check these:**

1. **Flow is published** (not in draft mode)
2. **Trigger matches exactly** - event names are case-sensitive
3. **Subscriber matches segment** if using segment filters
4. **Subscriber isn't in cooldown** from a previous flow run

---

## Getting Help {{ id: 'getting-help' }}

Still stuck? Here's how to get help:

| Channel                                          | Best For                          | Response Time     |
| ------------------------------------------------ | --------------------------------- | ----------------- |
| [Discord](https://discord.com/invite/ssXXFRmt5F) | Quick questions, community help   | Minutes to hours  |
| [Email](mailto:support@bentonow.com)             | Account issues, detailed problems | Same business day |
| [Status Page](https://status.bentonow.com)       | Checking if Bento is down         | Real-time         |

**When contacting support, include:**

- Your site UUID (helps us find your account)
- Steps to reproduce the issue
- Any error messages (exact text or screenshots)
- What you've already tried