Troubleshooting & FAQ

Common issues and frequently asked questions when working with DialogueDB.

Common Errors

401 Unauthorized

Symptom: All API requests return 401 Unauthorized.

Causes:

• Missing or invalid API key
• API key has been revoked or expired
• Wrong Authorization header format

Solution:

# Correct format - note the "Bearer " prefix
curl -H "Authorization: Bearer DIALOGUE_DB_API_KEY" \
  https://api.dialoguedb.com/dialogue

Make sure your API key starts with the correct prefix and has no extra whitespace.

---

403 Forbidden

Symptom: Requests return 403 Forbidden even with a valid API key.

Causes:

• API key belongs to a different project
• API key does not have permission for this operation

Solution:

• Verify you're using the API key for the correct project
• Check your API key permissions in the dashboard

---

404 Dialogue Not Found

Symptom: DIALOGUE_NOT_FOUND error when the dialogue exists.

Causes:

• Namespace mismatch: The dialogue was created with a namespace, but you're querying without one (or with a different one)
• Wrong project: Your API key is scoped to a different project than the one containing the dialogue
• Deleted: The dialogue was previously deleted

Solution:

// If the dialogue was created with a namespace, you need to provide it
const dialogue = await db.getDialogue(dialogueId, 'user_123');

// Or when using the REST API, ensure the same API key/project

---

429 Rate Limited

Symptom: RATE_LIMIT_EXCEEDED error with 429 status code.

Solution: Implement exponential backoff:

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED' && i < maxRetries - 1) {
        const delay = Math.min(1000 * Math.pow(2, i), 10000);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Check the Retry-After header for the recommended wait time. See your plan's rate limits in the dashboard.

---

SDK Issues

Wrong Import Path

Symptom: Cannot find module 'dialoguedb' or similar import error.

Solution: The correct package name is dialogue-db (with a hyphen):

// Correct
import { DialogueDB } from 'dialogue-db';

// Wrong
import { DialogueDB } from 'dialoguedb';

---

Config Not Set

Symptom: API key is required error when making SDK calls.

Solution: Make sure you pass the API key when creating the DialogueDB instance:

const db = new DialogueDB({
  apiKey: process.env.DIALOGUE_DB_API_KEY
});

---

TypeScript Type Errors

Symptom: TypeScript compilation errors with SDK types.

Solution: Ensure you're using the latest version of the SDK:

npm install dialogue-db@latest

The SDK exports all types you need:

import { DialogueDB, DialogueDBError } from 'dialogue-db';
import type { Dialogue, Message, Memory } from 'dialogue-db';

---

Error Class Name

Symptom: DialogueAPIError is not defined.

Solution: The correct error class name is DialogueDBError, not DialogueAPIError:

import { DialogueDB, DialogueDBError } from 'dialogue-db';

try {
  await db.getDialogue('invalid_id');
} catch (error) {
  if (error instanceof DialogueDBError) {
    console.log(error.code);       // e.g., 'DIALOGUE_NOT_FOUND'
    console.log(error.statusCode); // e.g., 404
  }
}

---

CORS Issues

SDK Requests Blocked by Browser

Symptom: CORS errors when calling DialogueDB from a browser application.

Cause: The DialogueDB SDK and API are designed for server-side use only. Making requests directly from a browser will fail due to CORS restrictions.

Solution: Create a backend proxy that forwards requests to DialogueDB:

// Backend (e.g., Express.js)
import { DialogueDB } from 'dialogue-db';

const db = new DialogueDB({
  apiKey: process.env.DIALOGUE_DB_API_KEY // Server-side only
});

app.post('/api/chat', async (req, res) => {
  const dialogue = await db.getDialogue(req.body.dialogueId);
  const message = await dialogue.saveMessage(req.body.message);
  res.json(message);
});

// Frontend
const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ dialogueId, message: { role: 'user', content: text } })
});

WARNING

Never expose your API key in client-side code. Always proxy through your backend.

---

Messages Not Appearing in Search

Symptom: A recently created message doesn't show up in search results.

Cause: Newly created content may take a few seconds to appear in search results.

Solution:

• Wait a few seconds before searching for newly created content
• For real-time lookups, use dialogue.loadMessages() or db.getDialogue() instead of search
• Search is optimized for finding content across your entire dataset, not for real-time queries

---

FAQ

What is the maximum message size?

Messages can be up to 1MB uncompressed. For larger content, store it externally and reference it via metadata:

await dialogue.saveMessage({
  role: 'assistant',
  content: 'See the attached document for full analysis.',
  metadata: { documentUrl: 'https://your-storage.com/doc/123' }
});

What are the rate limits per plan?

Rate limits vary by plan. Check the X-RateLimit-Limit and X-RateLimit-Remaining response headers to see your current limits. See the API Overview for rate limit details.

Can I update a message after creation?

No. Messages can't be changed after creation. To correct a message:

1. Delete the original message
2. Create a new message with the corrected content

await dialogue.deleteMessage(oldMessageId);
await dialogue.saveMessage({
  role: 'assistant',
  content: 'Corrected response...'
});

Can I update dialogue metadata after creation?

No. Dialogue metadata can't be changed after creation. Use these alternatives instead:

• tags - for categorization that may change
• label - for a human-readable identifier
• state - for data that changes during conversation

// Set mutable properties
dialogue.tags = ['resolved', 'billing'];
dialogue.label = 'Billing Issue #123';
await dialogue.save();

// Or update state
await dialogue.saveState({ status: 'resolved', resolvedAt: new Date().toISOString() });

How many messages can I create at once?

• On dialogue creation: Maximum 25 messages via the messages array
• After creation: Use dialogue.saveMessage() for single messages or dialogue.saveMessages() for batches

Is the SDK available for Python?

There is no official Python SDK yet. Use the requests library to call the REST API directly. Examples are included throughout the documentation.

import requests

response = requests.post(
    "https://api.dialoguedb.com/dialogue",
    headers={"Authorization": "Bearer DIALOGUE_DB_API_KEY"},
    json={"message": {"role": "user", "content": "Hello!"}}
)
dialogue = response.json()

Are end and compact actions available in the SDK?

end() is available — call await dialogue.end() to mark a dialogue as ended.

compact() is not yet implemented in the SDK. Calling it throws a DialogueDBError with code NOT_IMPLEMENTED. Use the REST API instead:

# Compact a dialogue (REST API only)
curl -X POST https://api.dialoguedb.com/dialogue/DIALOGUE_ID/compact \
  -H "Authorization: Bearer DIALOGUE_DB_API_KEY"

What's the difference between state and memory?

	State	Memory
Scope	Per-dialogue	Global / per-namespace
Lifespan	Tied to dialogue	Indefinite
Searchable	No	Yes (semantic search)
Updates	Full replace	Tags only (value can't change)
Use case	Session context, workflow progress	Long-term facts, preferences

---

Still Need Help?

• Check the Error Handling Guide for detailed error codes
• Review the API Reference for endpoint documentation
• Email: support@dialoguedb.com