Common authentication errors

If you're having trouble authenticating with the Cathopic API, these are the most common errors and how to fix them.

401 Unauthorized

The most common authentication error:

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Common causes:

• Missing x-api-key header

• Invalid or expired API key

• Typo in the API key

• Whitespace before/after the key

• Key not loaded from environment variable

How to fix:

1. Verify the header name is exactly x-api-key (lowercase)

2. Copy your API key again from Settings → API

3. Check environment variables are loaded: console.log(process.env.CATHOPIC_API_KEY)

4. Trim whitespace: apiKey.trim()

5. Verify the key is active (not deleted or deactivated)

Wrong header name

The API requires x-api-key, not other common header names:

// ❌ WRONG
Authorization: Bearer sk_live_abc...
API-Key: sk_live_abc...
apikey: sk_live_abc...
// ✅ CORRECT
x-api-key: sk_live_abc...

Unauthorized token error

HTTP 401 Unauthorized
{
  "error": "Unauthorized token"
}

Cause: Your API key has been deactivated or deleted.

How to fix:

• Check if the key is still active in Settings → API

• Reactivate the key if it was deactivated

• Generate a new key if the old one was deleted

Environment variable not loaded

Your code can't find the API key:

// Returns undefined
const apiKey = process.env.CATHOPIC_API_KEY;
console.log(apiKey); // undefined

How to fix:

Node.js:

// Make sure .env is loaded
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
if (!apiKey) {
  throw new Error('CATHOPIC_API_KEY not set');
}

Python:

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.environ.get('CATHOPIC_API_KEY')
if not api_key:
    raise ValueError('CATHOPIC_API_KEY not set')

Client-side exposure error

Trying to use API key in browser JavaScript:

// ❌ This will fail (keys don't work in browsers)
fetch('https://api.cathopic.com/resources', {
  headers: { 'x-api-key': 'sk_live_abc...' }
});

How to fix: Create a server-side endpoint that proxies requests to the Cathopic API. See "How do I secure my credentials?" for examples.

CORS errors

If you see CORS errors in the browser console:

Access to fetch has been blocked by CORS policy...

Cause: You're trying to call the API directly from client-side JavaScript.

How to fix: The Cathopic API is server-side only. You must proxy requests through your own backend.

Testing authentication

Quick test to verify your setup:

curl -v -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}'
# Look for HTTP 200 response
# If 401, check the key carefully

Debugging checklist

If authentication still fails:

• ☐ Header name is x-api-key (case sensitive)

• ☐ API key is the full key (starts with sk_live_ or similar)

• ☐ No Bearer prefix or quotes around the key

• ☐ Environment variable is set and loaded

• ☐ Request is sent from server-side, not browser

• ☐ Key is active in Settings → API

• ☐ Payment method is added and valid

If problems persist, contact developer support with:

• The error message

• Last 4 digits of your API key

• Programming language and framework

• Sample code (without exposing your full key)