# Error Handling & Troubleshooting

**GET /docs/error-handling**

## Common API Errors

### Authentication Errors
**Error:** "You need to sign in or sign up before continuing"
- **Cause:** Missing api_key parameter
- **Solution:** Include api_key from Cloud CMA Settings > API (or Account Settings > Integrations)

**Error:** "User with api_key not found"
- **Cause:** Invalid or expired API key
- **Solution:** Verify API key in Cloud CMA account settings; regenerate if needed

### Resource Not Found Errors
**Error:** "No matching listings were found on the MLS"
- **Cause:** Address is outside the MLS's operating boundary (e.g., subject property in Florida but user's MLS is California)
- **Solution:** Verify address is within the MLS service area; use MLS numbers when available instead of addresses

**Error:** Property address returns no results
- **Cause:** Address mistyped or not found in MLS database
- **Solution:** Use MLS number instead of address; verify spelling and format

### Feature/Permission Errors
**Error:** "This user does not have the Homebeat feature"
- **Cause:** Homebeat add-on is not enabled for this user or not available in this MLS
- **Solution:** Contact Cloud CMA support to enable Homebeat; verify it's available in your MLS

**Error:** "Frequency is not a valid option"
- **Cause:** Invalid frequency value provided for Homebeat
- **Solution:** Use one of the valid frequencies: monthly, quarterly, semi-annually, annually, never

### Homebeat Specific Issues
**Issue:** Welcome email not sent or subscription not active
- **Check:** Verify lead email address is valid and opted in
- **Check:** Confirm Homebeat feature is enabled for the user account
- **Check:** If using custom callback, ensure callback_url is accessible and returning 200 OK

**Issue:** Homebeat report shows no view counts
- **Cause:** Report may be too new or leads haven't viewed it yet
- **Solution:** Wait for updates according to the frequency (monthly, quarterly, etc.)

### Webhook Issues
**Webhooks not being called:**
- Verify callback_url is publicly accessible (not localhost)
- Ensure your endpoint returns HTTP 200 within 30 seconds
- Check server logs for incoming POST requests
- Cloud CMA will retry failed webhooks multiple times before giving up

**Webhook Payload Issues:**
- Verify you're parsing the JSON payload correctly
- All webhook payloads include: id, user_id, type, title, notes, mls_code, created_at, updated_at, deleted_at, edit_url, pdf_url, action, and job_id (if provided)

## Report Generation Issues
**Report takes longer than expected:**
- First report generation may take 1-2 minutes as Cloud CMA queries RETS and generates PDF
- Subsequent reports typically faster due to caching
- Check webhook callback for completion status

**PDF URL not working:**
- PDF URLs are temporarily available (typically 24-48 hours)
- For permanent storage, download PDF immediately after notification
- For permanent access, use edit_url to view in Cloud CMA interface

## Best Practices
1. Always use MLS numbers instead of addresses when available (more accurate, faster queries)
2. Implement webhook callbacks to track report status and delivery
3. Use job_id parameter to correlate callbacks with your internal systems
4. Handle webhook retries gracefully
5. Store pdf_url values immediately upon receipt; don't rely on them being available later
6. For lead captures, validate email addresses before submission


## Servers
- Production API: https://cloudcma.com (Production API)


## Authentication methods
- Api key


## Parameters




## Responses
### 200
Error Handling & Troubleshooting guide


[Powered by Bump.sh](https://bump.sh)