Troubleshooting

​

Quick Issue Resolution

​

Authentication Issues

​

”INVALID_API_KEY” Error

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

​

”MISSING_AUTH_HEADER” Error

• 401 error with message about missing authorization header

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

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

​

Version Header Missing

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

-H "Xerobi-Version: 2026-01-01"

​

Request/Response Issues

​

”INVALID_REQUEST” Errors

• Missing required fields
• Incorrect field types
• Malformed JSON

​

Rate Limiting

• 429 Too Many Requests
• RATE_LIMIT_EXCEEDED error

// 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

• CARD_DECLINED
• INSUFFICIENT_FUNDS
• EXPIRED_CARD

• 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

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

• 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 with curl
curl -X POST https://your-endpoint.com/webhooks \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'

​

SMS-Specific Issues

​

”INSUFFICIENT_BALANCE” Error

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Xerobi-Version: 2026-01-01" \
     https://api.hixbe.com/sms/balance

​

Delivery Failures

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

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

• VERIFICATION_FAILED error
• Credential appears invalid

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

​

Template Issues

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

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

​

Network and Connectivity

​

Timeout Issues

• Requests hang or timeout
• Intermittent connection failures

• 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

• SSL certificate verification errors
• Connection refused on 443

• 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

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

# 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

​

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

​

Use Request IDs

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

​

When to Contact Support

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

​

Support Request Template

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?

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