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