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/v1/posts"

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

# ✅ Correct - actual API key
curl "https://api.hivecms.online/api/public/v1/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/v1/{API_KEY}/posts"

# Then use a valid slug from the response
curl "https://api.hivecms.online/api/public/v1/{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

API Version Not Found (404)

What you see:

{
  "success": false,
  "code": "VERSION_NOT_FOUND",
  "message": "API version v99 not found"
}

Status Code: 404 Not Found

Possible causes:

• You're using an invalid or unsupported API version
• Typo in the version number in the URL

Solutions:

1. Check the URL format: /api/public/{VERSION}/{API_KEY}/...
2. Verify you're using a supported version (currently v1)
3. See API Versioning for current version information

Example:

# ❌ Wrong - unsupported version
curl "https://api.hivecms.online/api/public/v99/{API_KEY}/posts"

# ✅ Correct - use v1
curl "https://api.hivecms.online/api/public/v1/{API_KEY}/posts"

API Version Gone (410)

What you see:

{
  "success": false,
  "code": "API_VERSION_GONE",
  "message": "API version v1 is no longer supported",
  "migrate_to": "v2",
  "sunset_date": "2026-12-31T23:59:59Z"
}

Status Code: 410 Gone

Cause:

• The API version you're using has reached its sunset date and is no longer available
• This only happens after a deprecation period when clients have been warned

Solutions:

1. Update your integration to use the recommended version (see migrate_to in the error)
2. See API Versioning for migration guides
3. Review deprecation warnings in response headers before this occurs

Deprecation Warnings

What you see:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Mon, 31 Dec 2026 23:59:59 GMT
X-API-Suggest: v2

Meaning:

• Your API version is still working but will be sunset on the Sunset date
• You should plan to migrate to the suggested version
• After the sunset date, requests to this version will return 410 Gone

Solutions:

1. Monitor response headers for Deprecation: true
2. Plan migration to the version in X-API-Suggest
3. Reference API Versioning for migration details
4. Update your integration before the Sunset date

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/v1/${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/v1/${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