P
PUGUH
ID Get Started

Troubleshooting

Common issues and how to resolve them.

Authentication Issues

"Invalid or expired token"

JWT token has expired or is malformed.

Solution:

  1. Check token expiration time
  2. Refresh the token
  3. Re-authenticate if refresh fails
typescript 
try {
  await client.organizations.list();
} catch (error) {
  if (error.code === 'TOKEN_EXPIRED') {
    await client.auth.refresh();
    await client.organizations.list(); // Retry
  }
}

"API key not found"

Invalid or revoked API key.

Solution:

  1. Verify the API key is correct
  2. Check if the key was rotated
  3. Ensure the key is for the right organization

"Permission denied"

User lacks required permission.

Solution:

  1. Check user's role in IAM
  2. Verify the required permission
  3. Request role upgrade if needed
typescript 
// Check required permission
const hasPermission = await client.checkPermission('webhook.endpoints.create');
if (!hasPermission) {
  console.log('Contact your admin to request access');
}

Organization Issues

Cannot Create Organization

You may have reached the organization limit for your plan.

Solution:

  1. Check your current plan's organization limit
  2. Upgrade your plan if needed
  3. Contact support for enterprise limits

Member Invitation Not Working

Invitation email not received or invitation fails.

Debugging Steps:

  1. Check if the email address is correct
  2. Check spam/junk folders
  3. Verify your plan allows more members
  4. Check if the user is already a member

Webhook Issues

Webhook Not Receiving Events

External system not receiving webhook events.

Debugging Steps:

  1. Verify the webhook is active in Webhooks settings
  2. Check the webhook URL is reachable (HTTPS required)
  3. Review delivery history for error responses
  4. Test with the ping endpoint
typescript 
// Send a test ping
const result = await client.webhooks.test(webhookId);
console.log(result.status); // Check delivery status

Webhook Signature Verification Failing

Incorrect secret or payload parsing.

Solution:

typescript 
// Verify using the secret from webhook creation
const isValid = verifyWebhookSignature(
  req.rawBody, // Use raw body, not parsed JSON
  req.headers['x-puguh-signature'],
  webhookSecret
);

Performance Issues

Slow API Responses

API response time higher than expected.

Debugging:

1. Check Network Latency

  • Use regional API endpoints
  • Consider caching for repeated requests

Rate Limiting

429 errors.

Solution:

1. Check Usage

typescript 
const metrics = await client.control.getMetricsTrends({ period: '7d' });
console.log(`Events: ${metrics.totalEvents}`);

2. Implement Retry Logic

typescript 
const client = new PuguhClient({
  retries: 3,
  retryDelay: 1000,
});

3. Batch Requests

typescript 
// Instead of individual calls
const decisions = await client.decideBatch(requests);

4. Upgrade Plan - Higher plans have higher rate limits.

Data Issues

Missing Audit Entries

Expected events not appearing in audit trail.

Check:

1. Time Range - Expand date range in query. Check timezone settings.

2. Application Filter - Events might be in a different application. Check application scope.

3. Event Types - Verify you're filtering for the correct event type.

Audit Log Gaps

Missing entries in audit trail.

Causes:

  1. Retention Period - Free plan: 7 days. Check your plan's retention.
  2. Filter Settings - Remove filters to see all entries. Check action type filters.
  3. Export Archived Logs - Contact support for older logs (Enterprise).

Integration Issues

Webhook Not Firing

External system not receiving events.

Debugging:

1. Check Webhook Status - Go to Settings > Webhooks. Check webhook health status.

2. Verify Endpoint - Ensure URL is reachable. Check for HTTPS requirement.

3. Check Signature

typescript 
// Your webhook handler
const isValid = verifyWebhookSignature(
  req.body,
  req.headers['x-puguh-signature'],
  webhookSecret
);

4. Review Webhook Logs - Control > Events shows webhook delivery attempts. Check for error responses.

SDK Connection Issues

SDK calls timing out or failing.

Check:

1. Network Connectivity

bash 
curl https://api-puguh.arsaka.io/health

2. Firewall Rules - Ensure outbound HTTPS allowed. Check corporate proxy settings.

3. SDK Configuration

typescript 
const client = new PuguhClient({
  timeout: 30000, // Increase timeout
  baseUrl: 'https://api-puguh.arsaka.io', // Correct URL
});

Getting Help

If you can't resolve an issue:

  1. Check Status Page: https://status.arsaka.io
  2. Review Docs: Search documentation
  3. Contact Support: support@arsaka.io
  4. Include Details:
    • Organization ID
    • Timestamp of issue
    • Error messages
    • Steps to reproduce

Related