Troubleshooting

This guide covers the most common issues you might encounter when integrating with PromptGuard and provides step-by-step solutions.

Authentication Issues

Invalid API Key Error

Problem: Getting 401 Unauthorized errors when making requests. Symptoms:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Solutions:

Verify API Key Format

Check that your API key follows the correct format:

# Correct format
pg_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx  # Production
pg_test_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx  # Testing

# Check your key
echo $PROMPTGUARD_API_KEY | head -c 20
# Should show: pg_live_ or pg_test_

Check Environment Variables

Ensure your API key is properly set:

# Check if environment variable is set
echo $PROMPTGUARD_API_KEY

# For Node.js applications
console.log('API Key:', process.env.PROMPTGUARD_API_KEY?.substring(0, 10) + '...');

# For Python applications
import os
print(f"API Key: {os.environ.get('PROMPTGUARD_API_KEY', 'NOT_SET')[:10]}...")

Verify Key Status

Check if your API key is active in the dashboard:

Login to app.promptguard.co
Navigate to Settings > API Keys
Verify the key exists and is not revoked
Check the permissions assigned to the key

Permission Denied Error

Problem: API key lacks required permissions. Symptoms:

{
  "error": {
    "message": "API key lacks required permissions",
    "type": "permission_error",
    "code": "insufficient_permissions"
  }
}

Solutions:

Check key permissions in dashboard
Use a key with appropriate permissions (read/write/admin)
Contact your team admin to update permissions

Connection Issues

Network Timeout Errors

Problem: Requests timing out or failing to connect. Symptoms:

Connection timeout errors
Network unreachable errors
DNS resolution failures

Solutions:

Check Network Connectivity

Test basic connectivity to PromptGuard:

# Test DNS resolution
nslookup api.promptguard.co

# Test HTTP connectivity
curl -I https://api.promptguard.co/api/v1/models

# Test with your API key
curl https://api.promptguard.co/api/v1/models \
  -H "X-API-Key: $PROMPTGUARD_API_KEY"

Adjust Timeout Settings

Increase timeout values in your client:

// Node.js
const openai = new OpenAI({
  apiKey: process.env.PROMPTGUARD_API_KEY,
  baseURL: 'https://api.promptguard.co/api/v1',
  timeout: 60000 // 60 seconds
});

# Python
client = OpenAI(
    api_key=os.environ.get("PROMPTGUARD_API_KEY"),
    base_url="https://api.promptguard.co/api/v1",
    timeout=60.0
)

Check Firewall/Proxy Settings

Ensure your network allows outbound HTTPS connections:

Whitelist api.promptguard.co in firewall
Configure proxy settings if required
Check corporate network restrictions

Security Policy Issues

Unexpected Request Blocks

Problem: Legitimate requests being blocked by security policies. Symptoms:

{
  "error": {
    "message": "Request blocked by security policy",
    "type": "policy_violation",
    "code": "prompt_injection_detected"
  }
}

Solutions:

Review Security Events

Open app.promptguard.co
Navigate to Security > Events
Find the blocked request
Review the detection reason
Determine if it’s a false positive

Adjust Security Level

If you’re getting too many false positives:

Go to Security > Policies
Switch to a more permissive preset (e.g., from RAG System to Default)
Test your application
Gradually increase security as needed

Create Whitelist Rules

For legitimate patterns being blocked:

Navigate to Security > Custom Rules
Create an “Allow” rule for the specific pattern
Test to ensure the rule works correctly

High False Positive Rate

Problem: Too many legitimate requests being flagged as threats. Solutions:

Start with Default preset during development
Gradually increase security in staging
Monitor false positive rate in dashboard
Create custom whitelist rules for your use cases
Contact support for policy tuning assistance

Performance Issues

High Latency

Problem: Requests taking longer than expected. Expected Performance:

PromptGuard overhead: 30-50ms
Total latency: OpenAI/Anthropic latency + 30-50ms

Troubleshooting:

Measure Latency Components

async function measureLatency() {
  const start = Date.now();

  try {
    const response = await openai.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: 'Hello!' }]
    });

    const total = Date.now() - start;
    const pgOverhead = response.headers['x-promptguard-latency'];

    console.log(`Total: ${total}ms, PromptGuard: ${pgOverhead}ms`);

  } catch (error) {
    console.error('Request failed:', error);
  }
}

Optimize Client Configuration

// Use connection pooling
import https from 'https';

const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 20
});

const openai = new OpenAI({
  apiKey: process.env.PROMPTGUARD_API_KEY,
  baseURL: 'https://api.promptguard.co/api/v1',
  httpAgent: agent
});

Implement Request Caching

Cache responses for identical requests:

const cache = new Map();

async function cachedRequest(prompt) {
  const cacheKey = `${prompt}:gpt-4`;

  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const response = await openai.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: prompt }]
  });

  cache.set(cacheKey, response);
  return response;
}

Rate Limiting Issues

Too Many Requests Error

Problem: Hitting rate limits. Symptoms:

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "code": "too_many_requests"
  }
}

Solutions:

Implement Exponential Backoff

async function requestWithBackoff(requestFn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Check Rate Limit Headers

Monitor rate limit status:

const response = await openai.chat.completions.create({...});

console.log('Rate Limit Headers:');
console.log('Remaining:', response.headers['x-ratelimit-remaining']);
console.log('Reset:', response.headers['x-ratelimit-reset']);
console.log('Limit:', response.headers['x-ratelimit-limit']);

Distribute Load

Use multiple API keys to increase limits:

const apiKeys = [
  process.env.PROMPTGUARD_API_KEY_1,
  process.env.PROMPTGUARD_API_KEY_2,
  process.env.PROMPTGUARD_API_KEY_3
];

function getClient() {
  const keyIndex = Math.floor(Math.random() * apiKeys.length);
  return new OpenAI({
    apiKey: apiKeys[keyIndex],
    baseURL: 'https://api.promptguard.co/api/v1'
  });
}

Model and Provider Issues

Model Not Found Error

Problem: Specified model is not available. Symptoms:

{
  "error": {
    "message": "Model 'invalid-model' not found",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Solutions:

Check Supported Models

Verify the model name is correct:

# List available models
curl https://api.promptguard.co/v1/models \
  -H "X-API-Key: $PROMPTGUARD_API_KEY"

Supported models:

OpenAI: gpt-4, gpt-4-turbo, gpt-3.5-turbo
Anthropic: claude-3-5-sonnet-latest, claude-3-opus-20240229

Verify Provider Configuration

Ensure your provider API keys are configured:

Go to app.promptguard.co
Navigate to Settings > Provider Keys
Add your OpenAI and/or Anthropic API keys
Test the connection

Provider API Key Issues

Problem: Underlying provider (OpenAI/Anthropic) API key is invalid. Solutions:

Update provider keys in PromptGuard dashboard
Verify keys are active in provider’s dashboard
Check key permissions for the models you’re using
Ensure sufficient credits in provider account

Streaming Issues

Streaming Responses Cut Off

Problem: Streaming responses stop unexpectedly. Solutions:

Increase Function Timeouts

For serverless deployments:

// vercel.json
{
  "functions": {
    "api/chat/stream.js": {
      "maxDuration": 300
    }
  }
}

Handle Stream Errors

async function handleStream(stream) {
  try {
    for await (const chunk of stream) {
      const content = chunk.choices[0]?.delta?.content;
      if (content) {
        process.stdout.write(content);
      }
    }
  } catch (error) {
    console.error('Stream error:', error);
    // Implement fallback or retry logic
  }
}

Integration-Specific Issues

Next.js API Routes

Problem: Issues with Next.js API integration. Common Solutions:

Environment Variables

Ensure proper environment variable setup:

# .env.local
PROMPTGUARD_API_KEY=your_key_here

// Check in API route
console.log('API Key available:', !!process.env.PROMPTGUARD_API_KEY);

CORS Issues

Configure CORS for frontend requests:

// api/chat.js
export default async function handler(req, res) {
  // Add CORS headers
  res.setHeader('Access-Control-Allow-Origin', '*');
  res.setHeader('Access-Control-Allow-Methods', 'POST');
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');

  if (req.method === 'OPTIONS') {
    res.status(200).end();
    return;
  }

  // Your API logic here
}

Getting Help

Diagnostic Information

When contacting support, include:

# System information
node --version
npm --version

# Test basic connectivity
curl -I https://api.promptguard.co/v1/models

# Check API key format (first 10 characters only)
echo $PROMPTGUARD_API_KEY | head -c 10

# Recent error logs
tail -n 50 /path/to/your/app.log

Support Channels

Email Support

Technical support for integration issues

System Health

Check API status in real-time

Integration Guides

Complete integration guides and examples

Examples

See working code examples

Debug Mode

Enable debug logging for detailed troubleshooting:

// Node.js
process.env.DEBUG = 'openai:*';

// Or use console logging
const openai = new OpenAI({
  apiKey: process.env.PROMPTGUARD_API_KEY,
  baseURL: 'https://api.promptguard.co/v1',
  dangerouslyAllowBrowser: false, // Security check
  organization: undefined,
  project: undefined,
  defaultHeaders: {
    'X-Debug': 'true'
  }
});

Most issues can be resolved by following these troubleshooting steps. If you continue to experience problems, don’t hesitate to reach out to our support team with the diagnostic information above.

Getting Started

CLI & Editor Tools

Integration Guides

Security & Policies

Monitoring & Analytics

Advanced

Examples

Authentication Issues

Invalid API Key Error

Permission Denied Error

Connection Issues

Network Timeout Errors

Security Policy Issues

Unexpected Request Blocks

High False Positive Rate

Performance Issues

High Latency

Rate Limiting Issues

Too Many Requests Error

Model and Provider Issues

Model Not Found Error

Provider API Key Issues

Streaming Issues

Streaming Responses Cut Off

Integration-Specific Issues

Next.js API Routes

Getting Help

Diagnostic Information

Support Channels

Email Support

System Health

Integration Guides

Examples

Debug Mode

Getting Started

CLI & Editor Tools

Integration Guides

Security & Policies

Monitoring & Analytics

Advanced

Examples

​Authentication Issues

​Invalid API Key Error

​Permission Denied Error

​Connection Issues

​Network Timeout Errors

​Security Policy Issues

​Unexpected Request Blocks

​High False Positive Rate

​Performance Issues

​High Latency

​Rate Limiting Issues

​Too Many Requests Error

​Model and Provider Issues

​Model Not Found Error

​Provider API Key Issues

​Streaming Issues

​Streaming Responses Cut Off

​Integration-Specific Issues

​Next.js API Routes

​Getting Help

​Diagnostic Information

​Support Channels

Email Support

System Health

Integration Guides

Examples

​Debug Mode

Authentication Issues

Invalid API Key Error

Permission Denied Error

Connection Issues

Network Timeout Errors

Security Policy Issues

Unexpected Request Blocks

High False Positive Rate

Performance Issues

High Latency

Rate Limiting Issues

Too Many Requests Error

Model and Provider Issues

Model Not Found Error

Provider API Key Issues

Streaming Issues

Streaming Responses Cut Off

Integration-Specific Issues

Next.js API Routes

Getting Help

Diagnostic Information

Support Channels

Debug Mode