Troubleshooting

This page focuses on SDK-based integrations.

1. Request failed with 401

Cause: invalid/revoked key or wrong host/version path.

Fix:

• confirm HIVE_API_KEY
• confirm baseUrl is /api/public root
• confirm version is v1

2. Request failed with 404

Cause: route mismatch (often duplicated /v1 or wrong host).

Fix:

• use new Hive() with default HIVE_API_KEY first
• if overriding baseUrl, keep it as /api/public only
• test with await hive.stats.get() to verify connectivity

3. INVALID_API_RESPONSE

Cause: endpoint returned an unexpected payload shape.

Fix:

• check that your API host is actually Hive-compatible
• verify endpoint path and version
• inspect HiveApiError.details and error.message context fields

4. Reading SDK errors clearly

HiveApiError includes formatted lines with status, code, method, path, and url.

import { HiveApiError } from 'hive-cms';

try {
  await hive.posts.list();
} catch (error) {
  if (error instanceof HiveApiError) {
    console.error(error.message);
  }
}

5. Next.js and Express best practice

• call SDK in server runtime only (route handlers/controllers)
• avoid client-bundling API keys
• add caching where needed on your server boundary

Raw API troubleshooting

For HTTP-level errors, status codes, and versioning/sunset behavior, see API Reference.

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