Troubleshooting

Common issues and solutions for DeepMod integration. This guide helps you quickly identify and resolve problems with API integration, webhook handling, and content moderation.

API Issues

Authentication Problems

401 - Authentication Required

Your API token is missing, invalid, or malformed.

Symptoms:

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Authentication required"
}

Solutions:

• Verify your API token is correctly set in the Authorization header

• Ensure the token format is Bearer YOUR_API_TOKEN

• Check that your token hasn't been compromised or rotated

• Confirm you're using the correct token for your organization

Example Fix:

// ❌ Wrong
headers: { 'Authorization': 'YOUR_API_TOKEN' }

// ✅ Correct
headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }

403 - Insufficient Permissions

Your API token is valid but lacks necessary permissions.

Solutions:

• Verify your organization has an active subscription

• Check that your subscription hasn't expired

• Ensure you haven't exceeded your plan limits

• Contact support if permissions appear incorrect

Request Validation Errors

422 - Validation Failed

Request body or parameters don't meet API requirements.

Missing Required Fields:

{
  "code": "VALIDATION_ERROR",
  "status": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "policyId",
      "message": "The policyId field is required"
    }
  ]
}

Solutions:

• Ensure policyId and content are included in all moderation requests

• Verify policyId references an active policy

• Check that content is a non-empty string

• Validate metadata structure (must be valid JSON object)

Invalid Policy Reference:

• Policy ID doesn't exist or belongs to different organization

• Policy is inactive

• Using numeric ID when friendly identifier expected (or vice versa)

Content Issues:

• Empty or null content

• Content exceeds maximum size limits

• Invalid content encoding

Rate Limiting

429 - Too Many Requests

You're exceeding API rate limits.

Solutions:

• Implement exponential backoff retry logic

• Reduce request frequency

• Consider batching non-urgent requests

• Upgrade to higher plan for increased limits

Example Retry Implementation:

async function submitWithRetry(policyId, content, metadata, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.deepmod.ai/v1/moderation/run', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ policyId, content, metadata }),
      });

      if (response.status === 429) {
        throw new Error('Rate limited');
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Content Processing Errors

400 - Content Too Large

Content exceeds token limits for AI processing.

Error Message:

"Content is too long for moderation. Please reduce the content size."

Solutions:

• Reduce content length (DeepMod automatically chunks, but extremely large content may still exceed limits)

• Remove unnecessary boilerplate text before submission

• Split very large documents into logical sections

AI Service Errors

500 - AI Model Unavailable

Temporary issues with underlying AI services.

Common Messages:

• "AI model is temporarily unavailable. Please try again later."

• "Received invalid response from AI service. Please try again."

• "AI service error. Please try again later."

Solutions:

• Implement retry logic with exponential backoff

• These are usually temporary - retry after a few seconds

• Check DeepMod status page for known issues

• Contact support if errors persist

Webhook Issues

Webhook Delivery Problems

Moderation completes but no webhook arrives.

Diagnostic Steps:

1. Verify Webhook URL:

   • Confirm URL is publicly accessible

   • Test endpoint manually with a simple POST request

   • Check for HTTPS requirement

2. Check Webhook Configuration:

   • Organization must have valid webhook URL configured

   • Webhook URL cannot be localhost or private IP

   • URL must respond with 2xx status code

3. Review Server Logs:

   • Look for incoming POST requests to your webhook endpoint

   • Check for 4xx/5xx errors in your responses

   • Verify request handling is working correctly

Common Issues:

• Webhook URL returns non-2xx status codes

• Endpoint times out (must respond within 30 seconds)

• Server rejects requests due to missing headers

Webhook Verification Issues

Signature Verification Failing

Webhooks arrive but signature verification fails.

Troubleshooting Steps:

1. Check Client Secret:

   • Verify you're using the correct client secret from Organization Settings

   • Ensure secret hasn't been accidentally modified

2. Verify Signature Calculation:

   // Correct signature verification
   const crypto = require('crypto');
   
   function verifySignature(body, signature, secret) {
     const expectedSignature = crypto.createHmac('sha256', secret).update(body).digest('hex');
   
     return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature));
   }

   javascript

3. Raw Body Required:

   • Use raw request body, not parsed JSON

   • Signature is calculated on the exact bytes received

Webhook Timeouts

Webhook Processing Takes Too Long

DeepMod retries webhooks that don't respond quickly.

Solutions:

• Respond with 200 status immediately upon receipt

• Process webhook payload asynchronously

• Implement idempotent handling to avoid duplicate processing

Example Pattern:

app.post('/webhook', async (req, res) => {
  // Respond immediately
  res.status(200).send('OK');

  // Process asynchronously
  processWebhookAsync(req.body);
});

async function processWebhookAsync(payload) {
  // Your webhook processing logic here
  // This runs after the response is sent
}

Policy and Configuration Issues

Policy Activation Problems

Cannot Activate Policy

Policy activation fails despite appearing configured.

Common Causes:

• No webhook URL configured

• Webhook URL unreachable or returning errors

• Policy has no rule groups or rules

• All rules are invalid or empty

Solutions:

1. Configure valid webhook URL in Organization Settings

2. Test webhook endpoint manually

3. Ensure policy has at least one rule group with valid rules

4. Review rule validation errors in dashboard

Unexpected Moderation Results

All Content Being Flagged/Approved

Results don't match expectations.

Diagnostic Steps:

1. Review Rule Configuration:

   • Check rule content and descriptions

   • Verify rule groups are properly configured

   • Test rules individually using the policy tester

2. Check Confidence Threshold:

   • Lower thresholds = more sensitive (more ambiguous results)

   • Higher thresholds = less sensitive (more definitive results)

   • Optimal range is typically 0.6-0.8

3. Validate Test Content:

   • Use diverse test cases

   • Include clear violations and clear approvals

   • Test edge cases and ambiguous content

Performance Issues

Slow Response Times

Moderation Taking Too Long

Processing time exceeds expected duration.

Factors Affecting Speed:

• Content length (longer content takes more time)

• Policy complexity (more rules = longer processing)

• Current system load

• Network latency

Optimization Strategies:

• Remove unnecessary rules from policies

• Use more specific, focused rules

• Clean content before submission (remove boilerplate)

• Implement proper error handling and timeouts

High Ambiguous Results

Too Many Moderation Results Require Review

Excessive ambiguous outcomes impact workflow efficiency.

Solutions:

1. Adjust Confidence Threshold:

   • Start with 0.7 and adjust based on results

   • Lower for more definitive decisions (may increase false positives/negatives)

   • Higher for more conservative approach (more manual review)

2. Improve Rule Clarity:

   • Use specific, concrete rule descriptions

   • Avoid vague or overly broad rules

   • Include clear examples of violations

3. Policy Structure:

   • Group related rules logically

   • Ensure rules don't conflict with each other

   • Test rule combinations thoroughly

Getting Help

Before Contacting Support

Information to Gather:

1. API Issues:

   • Full error message and HTTP status code

   • Request details (endpoint, headers, body)

   • API token (last 4 characters only)

   • Timestamp of the issue

2. Webhook Issues:

   • Webhook URL being used

   • Expected vs. actual behavior

   • Server logs showing incoming requests

   • Signature verification implementation

3. Moderation Issues:

   • Policy ID and name

   • Sample content that's not working as expected

   • Expected vs. actual results

   • Confidence threshold settings

Still having issues? Contact support with the debug information above for faster resolution.