Troubleshooting

Common issues and solutions for Hixbe API integrations

Quick Issue Resolution

Find solutions to the most common integration problems developers face with Hixbe APIs.

Authentication Issues

”INVALID_API_KEY” Error

Symptoms:

• All API requests return 401 Unauthorized
• Error message: “The API key provided is invalid”

Solutions:

1. Check API key format

   Ensure your API key starts with the correct prefix:

   • Secret keys: sk_live_ or sk_test_
   • Publishable keys: pk_live_ or pk_test_
2. Verify key is active

   Log into your dashboard and check:

   • API key is not expired
   • API key has required permissions
   • Account is in good standing
3. Check environment

   • Use sandbox keys for testing: https://sandbox.api.hixbe.com
   • Use production keys for live: https://api.hixbe.com

”MISSING_AUTH_HEADER” Error

Symptoms:

• 401 error with message about missing authorization header

Common Causes:

• Authorization header not included
• Incorrect header format
• API key not properly encoded

Fix:

# Correct format
curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Hixbe-Version: 2026-01-01" \
     https://api.hixbe.com/payment/payment_intents

Version Header Missing

Symptoms:

• 400 Bad Request with “Hixbe-Version header is required”

Solution: Always include the version header:

-H "Hixbe-Version: 2026-01-01"

Request/Response Issues

”INVALID_REQUEST” Errors

Common Causes:

• Missing required fields
• Incorrect field types
• Malformed JSON

Debug Steps:

1. Validate JSON syntax

   Use a JSON validator to check your request body

2. Check required fields

   Review API documentation for mandatory fields

3. Verify field types

   Ensure amounts are integers (cents), dates are ISO 8601 format

Rate Limiting

Symptoms:

• 429 Too Many Requests
• RATE_LIMIT_EXCEEDED error

Solutions:

// Implement exponential backoff
async function makeRequestWithRetry(endpoint, data, attempt = 0) {
  try {
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: { /* your headers */ },
      body: JSON.stringify(data)
    });

    if (response.status === 429) {
      const retryAfter = response.headers.get('X-RateLimit-Retry-After');
      const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;

      await new Promise(resolve => setTimeout(resolve, delay));
      return makeRequestWithRetry(endpoint, data, attempt + 1);
    }

    return response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

Payment-Specific Issues

Payment Declines

Error Codes:

• CARD_DECLINED
• INSUFFICIENT_FUNDS
• EXPIRED_CARD

Troubleshooting:

• Verify card details are correct
• Check card has sufficient funds
• Ensure card is not expired
• Try different card or payment method
• Contact card issuer if issue persists

Webhook Delivery Issues

Symptoms:

• Webhooks not being received
• Events not triggering in your application

Debug Checklist:

• Webhook URL is publicly accessible and uses HTTPS
• Endpoint returns 200 status code within 10 seconds
• Webhook signature verification is implemented
• Firewall allows incoming POST requests
• Endpoint can handle the expected payload size

Test Webhook:

# Test with curl
curl -X POST https://your-endpoint.com/webhooks \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'

SMS-Specific Issues

”INSUFFICIENT_BALANCE” Error

Solution:

1. Check balance

   curl -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Hixbe-Version: 2026-01-01" \
        https://api.hixbe.com/sms/balance
   
2. Top up account

   Log into dashboard and add credits

3. Set up balance alerts

   Configure webhooks for low balance notifications

Delivery Failures

Common Issues:

• Invalid phone number format
• Recipient opted out of SMS
• Carrier filtering
• International routing issues

Validation:

function validatePhoneNumber(phone) {
  // Remove all non-digit characters
  const cleaned = phone.replace(/\D/g, '');

  // Check length (10-15 digits for international)
  if (cleaned.length < 10 || cleaned.length > 15) {
    return false;
  }

  // Should start with country code
  return cleaned.length > 10;
}

Certification Issues

Credential Verification Failures

Symptoms:

• VERIFICATION_FAILED error
• Credential appears invalid

Troubleshooting:

• Verify credential ID format
• Check credential hasn’t expired
• Ensure issuer is trusted
• Validate against original credential data
• Check revocation status

Template Issues

Common Problems:

• Template not found
• Invalid template data
• Missing required fields

Solution: List available templates first:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Hixbe-Version: 2026-01-01" \
     https://api.hixbe.com/certify/templates

Network and Connectivity

Timeout Issues

Symptoms:

• Requests hang or timeout
• Intermittent connection failures

Solutions:

• Increase timeout values (recommended: 30 seconds)
• Implement retry logic with backoff
• Check network connectivity
• Verify DNS resolution
• Use connection pooling for high traffic

const client = new ApiClient({
  timeout: 30000, // 30 seconds
  retries: 3,
  retryDelay: 1000
});

SSL/TLS Issues

Symptoms:

• SSL certificate verification errors
• Connection refused on 443

Fixes:

• Ensure system has up-to-date CA certificates
• Use TLS 1.2 or higher
• Verify certificate is not expired
• Check firewall allows HTTPS traffic

Development Environment Issues

Local Development Problems

Common Issues:

• CORS errors in browser
• Localhost not accessible from external services
• Environment variable issues

Solutions:

# Use ngrok for local webhook testing
npm install -g ngrok
ngrok http 3000

# Set environment variables
export HIXBE_API_KEY=sk_test_...
export HIXBE_VERSION=2026-01-01

Sandbox vs Production

Configuration Differences:

Setting	Sandbox	Production
Base URL	sandbox.api.hixbe.com	api.hixbe.com
API Keys	Test keys only	Live keys only
Data	Isolated test data	Real production data
Rate Limits	Higher limits	Standard limits

Monitoring and Debugging

Enable Debug Logging

const client = new HixbeClient({
  apiKey: process.env.HIXBE_API_KEY,
  debug: true, // Enable detailed logging
  logger: console
});

Check API Status

Visit status.hixbe.com for real-time API status and incident reports.

Use Request IDs

All API responses include an X-Request-ID header for tracking:

const response = await fetch(endpoint, options);
const requestId = response.headers.get('X-Request-ID');

console.log(`Request ID: ${requestId}`); // Use for support tickets

Getting Help

Support Resources

API Reference

Complete API documentation with examples

Payment FAQ

Payment-specific questions and solutions

SMS FAQ

SMS-specific questions and solutions

Certification FAQ

Certification-specific questions and solutions

Community Forum

Connect with other developers

Status Page

Real-time API status and incidents

Support Ticket

Submit detailed support requests

When to Contact Support

• Persistent authentication failures
• Unexpected API behavior
• Account or billing issues
• Security concerns
• Feature requests
• Integration blockers

Support Request Template

When contacting support, include:

Subject: [API] Issue with Payment Intent Creation

Environment: Production/Sandbox
API Version: 2026-01-01
Request ID: req_1234567890
Timestamp: 2025-12-03 10:30:00 UTC

Description:
[Describe the issue clearly]

Steps to Reproduce:
1. [Step 1]
2. [Step 2]
3. [Expected vs Actual behavior]

Request Payload:
[Include relevant API request]

Response:
[Include API response or error]

Additional Context:
[Any other relevant information]

Prevention Best Practices

• Test thoroughly in sandbox before production
• Implement proper error handling and retries
• Monitor API usage and error rates
• Keep API keys secure and rotate regularly
• Stay updated with API changes via changelog
• Use the latest API version
• Implement comprehensive logging

Still Having Issues?

If you can’t find a solution above:

1. Check the changelog for recent changes
2. Review API documentation for your specific use case
3. Test in sandbox to isolate the issue
4. Contact support with detailed information

Contact Support

Get personalized help from our support team