Troubleshooting

This guide helps you resolve common issues when working with the Hive Public Content API.

Common Errors

Invalid API Key (401 Unauthorized)

What you see:

{
  "message": "Invalid API key"
}

Status Code: 401 Unauthorized

Possible causes:

• The API key is missing from the URL
• The API key is incorrect or has been revoked
• The API key contains extra spaces or characters

Solutions:

1. Verify you copied the API key exactly as provided
2. Check that the key is included in the URL path: /api/public/{API_KEY}/...
3. Ensure there are no extra spaces or line breaks in the key
4. Generate a new API key from your workspace if needed

Example:

# ❌ Wrong - missing API key
curl "https://api.hivecms.online/api/public/posts"

# ❌ Wrong - incorrect key format
curl "https://api.hivecms.online/api/public/{API_KEY}/posts"

# ✅ Correct - actual API key
curl "https://api.hivecms.online/api/public/your-actual-key-here/posts"

Post Not Found (404 Not Found)

What you see:

{
  "message": "Post not found"
}

Status Code: 404 Not Found

Possible causes:

• The post slug doesn't exist
• The post slug is misspelled
• The post has been deleted or unpublished

Solutions:

1. Verify the post slug in your Hive workspace
2. Check for typos in the slug (case-sensitive)
3. Ensure the post is published
4. Use the Posts list endpoint to get valid slugs

Example:

# First, get a list of posts to find valid slugs
curl "https://api.hivecms.online/api/public/{API_KEY}/posts"

# Then use a valid slug from the response
curl "https://api.hivecms.online/api/public/{API_KEY}/posts/valid-slug-here"

Server Error (500 Internal Server Error)

What you see:

{
  "message": "Failed to fetch ..."
}

Status Code: 500 Internal Server Error

Possible causes:

• Temporary server issue
• Database connection problem
• Unexpected error on the server

Solutions:

1. Wait a moment and try the request again
2. Check if the issue persists with a simple endpoint (e.g., /stats)
3. If the problem continues, contact Hive support with:
   • The endpoint you're calling
   • The error message
   • The timestamp of the error

Rate Limiting

What you see:

{
  "message": "Rate limit exceeded"
}

Status Code: 429 Too Many Requests

Solutions:

1. Reduce the frequency of your API calls
2. Implement request caching on your side
3. Use pagination to fetch data in batches rather than making many small requests

Best Practices

Caching Responses

Cache API responses on your side to reduce requests and improve performance:

// Simple caching example
const cache = new Map();

async function getCachedPosts(apiKey) {
  const cacheKey = 'posts';
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }

  const response = await fetch(
    `https://api.hivecms.online/api/public/${apiKey}/posts`
  );
  const data = await response.json();
  
  // Cache for 5 minutes
  cache.set(cacheKey, data);
  setTimeout(() => cache.delete(cacheKey), 5 * 60 * 1000);
  
  return data;
}

Error Handling

Always handle errors gracefully:

async function fetchPosts(apiKey) {
  try {
    const response = await fetch(
      `https://api.hivecms.online/api/public/${apiKey}/posts`
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'Failed to fetch posts');
    }

    return await response.json();
  } catch (error) {
    console.error('Error fetching posts:', error);
    // Handle error appropriately (show message, retry, etc.)
    throw error;
  }
}

Validating Responses

Validate API responses before using them:

function validatePostListResponse(data) {
  if (!data || !Array.isArray(data.data)) {
    throw new Error('Invalid response format');
  }
  return data;
}

Getting Help

If you continue to experience issues:

1. Check the documentation: Review the relevant endpoint documentation
2. Verify your setup: Ensure your API key is correct and the base URL is accurate
3. Test with cURL: Use the provided cURL examples to isolate the issue
4. Contact support: Reach out to Hive support with:
   • Your API key (you can redact part of it)
   • The endpoint you're calling
   • The full error message
   • Steps to reproduce the issue

Quick Reference