Troubleshooting Guide
Common issues and solutions when working with the InnKeeper API and Oracle OHIP integration.
Quick Diagnostics
Run this checklist first:
# 1. Check API health
curl https://xyz.convex.site/api/v1/health
# 2. Verify authentication
curl https://xyz.convex.site/api/v1/task-manager/requests?entityId=YOUR_ID \
-H "x-app-key: YOUR_API_KEY"
# 3. Check rate limits
curl -I https://xyz.convex.site/api/v1/health | grep X-RateLimit
# 4. Test webhook endpoint
curl -X POST https://xyz.convex.site/api/v1/webhooks/oracle/reservations \
-H "Content-Type: application/json" \
-d '{"eventType":"test"}'Authentication Issues
401 Unauthorized - Invalid API Key
Error:
"Invalid API key"Causes & Solutions:
1. Wrong API key
# Verify your key echo $INNKEEPER_API_KEY # Should start with sk_live_ or sk_test_
2. Extra whitespace
# Trim whitespace export INNKEEPER_API_KEY=$(echo "$INNKEEPER_API_KEY" | tr -d '[:space:]')
- Test keys don't work in production
- Production keys don't work in development
- Key may have been revoked - contact api@innkeeper.africa
401 Unauthorized - Token Expired
Error:
"Token has expired"Solutions:
- Implement automatic token refresh
- Check system clock is synchronized (NTP)
- Request new token before 2-minute expiry buffer
403 Forbidden - Insufficient Scopes
Error:
"Insufficient permissions for this operation"Solutions:
- Request additional scopes when getting token
- Check scope string format (space-separated)
- Contact support to enable scope for your account
API Request Issues
400 Bad Request - Missing Required Field
Error:
"Missing required field: categoryId"Solutions:
Check required fields:
const request = {
title: "...", // Required
description: "...", // Required
priority: "MEDIUM", // Required
categoryId: "...", // Required - DON'T FORGET!
entityId: "..." // Required
};404 Not Found - Resource Not Found
Error:
"Request not found"Possible Causes:
- Wrong ID - Check you're using the correct ID format
- Deleted resource - Resource may have been removed
- Wrong entity - Resource belongs to different entity
- Typo in URL - Verify endpoint path
429 Too Many Requests - Rate Limited
Error:
"Rate limit exceeded. Try again in 30 seconds"Solutions:
1. Implement exponential backoff:
async function makeRequestWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const response = await fetch(url, options);
if (response.status !== 429) {
return response;
}
const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
const delay = Math.min(retryAfter * 1000 * Math.pow(2, i), 60000);
console.log(`Rate limited. Retrying in ${delay}ms...`);
await sleep(delay);
}
throw new Error('Max retries exceeded');
}- Check
X-RateLimit-Resetheader - Upgrade to premium tier (1000 req/min)
- Cache responses when possible
- Batch operations instead of individual requests
Webhook Issues
Webhook Signature Verification Failed
Error:
"Webhook verification failed"Solutions:
- Verify webhook secret matches exactly
- Check signature format:
sha256=<hash> - Ensure payload matches what was signed
- Verify timestamp is within 5-minute window
- Check for trailing whitespace in secret
Webhook Not Received
Checklist:
- Verify URL is publicly accessible (not localhost)
- Check firewall allows Oracle IP ranges
- Ensure HTTPS endpoint (required by Oracle)
- Test endpoint manually with curl
- Check Oracle webhook configuration
- Review Oracle webhook delivery logs
Duplicate Webhook Events
Problem: Same event processed multiple times
Solutions:
- Implement idempotency using
eventId - Store processed event IDs in database/cache
- Return cached response for duplicates
- Don't rely on network-level deduplication
Connection Issues
Network Timeout
Error:
Error: ETIMEDOUTSolutions:
- Increase timeout (default is usually 30 seconds)
- Check network connectivity with ping/curl
- Verify DNS resolution
- Check proxy settings if behind corporate firewall
SSL/TLS Errors
Error:
unable to verify the first certificateSolutions:
Update CA certificates:
# macOS brew install ca-certificates # Ubuntu/Debian sudo apt-get update && sudo apt-get install ca-certificates # CentOS/RHEL sudo yum install ca-certificates
Common Error Codes
| Code | Meaning | Common Cause | Solution |
|---|---|---|---|
| 400 | Bad Request | Missing/invalid fields | Check request body |
| 401 | Unauthorized | Invalid credentials | Verify API key/token |
| 403 | Forbidden | Insufficient permissions | Request additional scopes |
| 404 | Not Found | Resource doesn't exist | Verify ID is correct |
| 409 | Conflict | Duplicate resource | Use different identifier |
| 429 | Too Many Requests | Rate limit exceeded | Implement backoff |
| 500 | Internal Server Error | Server issue | Retry, contact support |
| 503 | Service Unavailable | Maintenance/overload | Check status page |
Best Practices to Avoid Issues
- Always validate input before sending requests
- Implement retry logic with exponential backoff
- Cache responses when appropriate
- Monitor rate limits proactively
- Log requests and responses for debugging
- Use idempotency keys for create operations
- Handle errors gracefully with user-friendly messages
- Keep credentials secure in environment variables
- Test in sandbox before production deployment
- Subscribe to status updates at status.innkeeper.africa
Getting Help
Collect Debug Information
When contacting support, include:
# 1. API version curl https://xyz.convex.site/api/v1/health # 2. Request/response with verbose output curl -v https://xyz.convex.site/api/v1/... \ -H "x-app-key: YOUR_KEY" \ > debug.log 2>&1 # 3. Environment details echo "Node version: $(node --version)" echo "Platform: $(uname -a)" # 4. Error trace ID (from error response) # Include the traceId from error response
Support Channels
📧
🌐
Escalation for Critical Issues
- Email: urgent@innkeeper.africa
- Subject: [URGENT] Brief description
- Include: Account ID, error details, business impact
- Expected response: < 1 hour during business hours