Troubleshooting

Common issues and solutions when working with Inodra's Sui infrastructure.

Authentication Issues

Invalid API Key (401)

Symptoms: API requests return 401 Unauthorized

Solutions:

Verify API Key Format
- Keys should start with indr_
- Check for extra whitespace or copy-paste errors
Check Dashboard
- Log into inodra.com/dashboard
- Verify key status is "Active"
- Ensure usage limits haven't been exceeded

Correct Header Format

javascript

// Primary method (recommended)
headers: {
  'x-api-key': 'indr_abc123...'
}

// Alternative (also works)
headers: {
  'Authorization': 'Bearer indr_abc123...'
}

// Common mistakes
headers: {
  'X-API-KEY': 'indr_abc123...', // Wrong! Case sensitive
  'api-key': 'indr_abc123...'     // Wrong! Must be x-api-key
}

Rate Limit Exceeded (429)

Symptoms: API returns HTTP 429 Too Many Requests

Solutions:

Check Rate Limit Headers

bash

curl -I -H "x-api-key: YOUR_KEY" https://api.inodra.com/v1/checkpoints

# Look for these headers:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 50
# X-RateLimit-Reset: 1640995200
# Retry-After: 60

Implement Exponential Backoff

javascript

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options)

    if (response.status === 429) {
      const retryAfter = response.headers.get('retry-after') || Math.pow(2, i)
      await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000))
      continue
    }

    return response
  }
}

Optimize Request Patterns
- Use pagination for large datasets
- Cache frequently accessed data
- Batch requests when possible
- Consider upgrading plan for higher limits

Connection Issues

Request Timeouts

Symptoms: Requests timeout or take very long

Solutions:

Increase Timeout Values

javascript

const response = await fetch('https://api.inodra.com/v1/transactions', {
  headers: { 'x-api-key': 'YOUR_KEY' },
  signal: AbortSignal.timeout(30000) // 30 seconds
})

Use Pagination

javascript

// Request smaller chunks
const response = await fetch('/v1/transactions?limit=100')

Test Connectivity

bash

ping api.inodra.com
curl -I https://api.inodra.com/health

DNS Resolution Issues

Symptoms: Cannot resolve api.inodra.com

Solutions:

bash

# Test DNS resolution
nslookup api.inodra.com
dig api.inodra.com

# Try alternative DNS servers
# Google DNS: 8.8.8.8, 8.8.4.4
# Cloudflare DNS: 1.1.1.1, 1.0.0.1

Webhook Issues

Not Receiving Events

Symptoms: Webhooks created but no events received

Solutions:

Test Webhook URL

bash

curl -X POST https://your-domain.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Verify Event Filters
- Check event type format: package::module::Event
- Remove sender filter to test broader scope
- Confirm events are actually occurring on blockchain
Check HTTPS
- Webhook URLs must use HTTPS in production
- Verify SSL certificate validity
- Test: openssl s_client -connect your-domain.com:443

Duplicate Events

Symptoms: Same event delivered multiple times

Cause: Webhooks use at-least-once delivery (normal behavior)

Solution:

javascript

// Implement idempotency
const processedEvents = new Set()

app.post('/webhook', (req, res) => {
  const eventId = req.body.id

  if (processedEvents.has(eventId)) {
    return res.status(200).send('Already processed')
  }

  processedEvents.add(eventId)
  processEvent(req.body)
  res.status(200).send('OK')
})

Processing Timeouts

Symptoms: Webhook deliveries marked as failed

Cause: Endpoint takes > 10 seconds to respond

Solution:

javascript

// Return 200 immediately, process async
app.post('/webhook', (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).send('OK')

  // Process in background
  processWebhookAsync(req.body)
})

async function processWebhookAsync(event) {
  try {
    await processEvent(event)
  } catch (error) {
    console.error('Webhook processing failed:', error)
  }
}

Data Issues

Transaction Not Found (404)

Symptoms: API returns 404 for valid transaction digest

Causes:

Transaction very recent (not yet indexed)
Invalid digest format

Solutions:

Wait and Retry for recent transactions

javascript

async function getTransactionWithRetry(digest, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fetch(`/v1/transactions/${digest}`)
    } catch (error) {
      if (error.status === 404 && i < maxRetries - 1) {
        await new Promise((resolve) => setTimeout(resolve, 2000))
        continue
      }
      throw error
    }
  }
}

Validate Digest Format

javascript

function isValidTxDigest(digest) {
  return /^[1-9A-HJ-NP-Za-km-z]{44}$/.test(digest)
}

Response Format Issues

Symptoms: Response doesn't match expected schema

Solutions:

Check Response Headers

javascript

const response = await fetch('/v1/checkpoints')
console.log('Content-Type:', response.headers.get('content-type'))
console.log('API-Version:', response.headers.get('x-api-version'))

Validate JSON

javascript

try {
  const data = await response.json()
} catch (error) {
  console.error('Invalid JSON:', await response.text())
}

Check API Documentation
- Visit api.inodra.com/docs
- Verify endpoint exists and format
- Review the API Reference for current specifications

Performance Optimization

Slow Response Times

Solutions:

Use Pagination

javascript

// Request smaller chunks
const fetchTransactions = async (address, limit = 100) => {
  let allTxs = []
  let cursor = null

  do {
    const params = new URLSearchParams({ limit })
    if (cursor) params.set('cursor', cursor)

    const response = await fetch(`/v1/accounts/${address}/transactions?${params}`)
    const data = await response.json()

    allTxs.push(...data.data)
    cursor = data.pagination?.cursor
  } while (cursor)

  return allTxs
}

Use Specific Endpoints

javascript

// Good: Get only what you need
const balance = await fetch(`/v1/accounts/${address}/balance`)

// Avoid: Get everything then extract what you need
const account = await fetch(`/v1/accounts/${address}`)

Implement Caching

javascript

const cache = new Map()

async function getCachedData(url, ttl = 60000) {
  const cached = cache.get(url)

  if (cached && Date.now() - cached.timestamp < ttl) {
    return cached.data
  }

  const data = await fetch(url).then((r) => r.json())
  cache.set(url, { data, timestamp: Date.now() })

  return data
}

Getting Help

Support Channels

Interactive Documentation - Try endpoints live
Status Page - Check service status
Discord Community - Community support
Support Email - Direct support

Diagnostic Information

When contacting support, include:

Full Request

bash

curl -v -H "x-api-key: indr_xxx" \
  "https://api.inodra.com/v1/checkpoints"

Error Details
- Full error response body
- HTTP status code
- Timestamp of issue
Environment
- Operating system
- Programming language/version
- Library versions (if applicable)

Troubleshooting ​

Authentication Issues ​

Invalid API Key (401) ​

Rate Limit Exceeded (429) ​

Connection Issues ​

Request Timeouts ​

DNS Resolution Issues ​

Webhook Issues ​

Not Receiving Events ​

Duplicate Events ​

Processing Timeouts ​

Data Issues ​

Transaction Not Found (404) ​

Response Format Issues ​

Performance Optimization ​

Slow Response Times ​

Getting Help ​

Support Channels ​

Diagnostic Information ​

Troubleshooting

Authentication Issues

Invalid API Key (401)

Rate Limit Exceeded (429)

Connection Issues

Request Timeouts

DNS Resolution Issues

Webhook Issues

Not Receiving Events

Duplicate Events

Processing Timeouts

Data Issues

Transaction Not Found (404)

Response Format Issues

Performance Optimization

Slow Response Times

Getting Help

Support Channels

Diagnostic Information