Troubleshooting

This guide provides solutions to common issues encountered when integrating with AS2aaS.

Table of Contents

• Authentication Issues
• Message Delivery Problems
• Partner Configuration Issues
• Certificate Problems
• Webhook Delivery Issues
• Performance Issues
• Getting Support

Authentication Issues

Invalid API Key Error

Symptoms:

• HTTP 401 Unauthorized responses
• Error message: "Unauthenticated" or "Invalid API key"

Diagnostic Steps:

Solutions:

Rate Limiting

Symptoms:

• HTTP 429 Too Many Requests
• X-RateLimit-Remaining: 0 header

Rate Limits by Plan:

Implementation:

async function makeApiRequestWithBackoff(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After')) || Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

Message Delivery Problems

Message Stuck in "Queued" Status

Diagnostic Steps:

Common Causes:

MDN Not Received

Diagnostic Checklist:

MDN Troubleshooting:

# Check message MDN status
GET /v1/messages/{message_id}

# Look for mdn_status field:
# - "pending": MDN requested but not received
# - "received": MDN successfully received  
# - "failed": MDN delivery failed
# - "timeout": MDN not received within timeout

Partner Configuration Issues

Partner Connection Test Failures

Test Types and Common Failures:

Connection Test Response Analysis:

{
  "success": false,
  "results": {
    "connectivity": "failed",
    "error": "Connection timeout"
  },
  "timeline": [
    {
      "step": "DNS resolution",
      "status": "success",
      "duration_ms": 15
    },
    {
      "step": "TCP connection", 
      "status": "failure",
      "duration_ms": 60000,
      "details": "Connection timeout after 60 seconds"
    }
  ]
}

AS2 ID Configuration Problems

Validation Rules:

Certificate Problems

Certificate Upload Failures

Common Certificate Issues:

Certificate Format Requirements:

Certificate Validation

Validation Process:

POST /v1/certificates/{id}/validate

Validation Checks:

Webhook Delivery Issues

Webhook Endpoint Not Receiving Events

Diagnostic Steps:

Webhook Requirements:

Webhook Signature Verification

Signature Verification Implementation:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature.replace('sha256=', ''), 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

Common Signature Issues:

Performance Issues

Slow API Responses

Performance Optimization:

Optimal Request Patterns:

Message Processing Delays

Processing Time Factors:

Getting Support

Self-Service Resources

Information to Include When Contacting Support

For Message Issues

• Message ID
• Partner ID
• Timestamp of issue
• Error message or status
• Expected vs actual behavior

For Partner Issues

• Partner ID
• AS2 ID
• Partner endpoint URL
• Connection test results
• Certificate information

For API Issues

• HTTP status code
• Complete error response
• Request details (without sensitive data)
• API key prefix (not full key)
• Timestamp of request

Support Channels

Escalation Process

1. Self-service - Check documentation and status page
2. Dashboard tools - Use testing and diagnostic tools
3. Email support - Provide detailed issue description
4. Phone support - Enterprise customers for urgent issues
5. Emergency escalation - Production-critical issues only

Diagnostic Commands

Quick Health Check

# Test API connectivity
curl -H "Authorization: Bearer pk_test_your_key" \
     https://api.as2aas.com/v1/partners

# Check specific partner
curl -H "Authorization: Bearer pk_test_your_key" \
     https://api.as2aas.com/v1/partners/prt_000001

# Test partner connection
curl -X POST \
     -H "Authorization: Bearer pk_test_your_key" \
     -H "Content-Type: application/json" \
     -d '{"test_type": "ping"}' \
     https://api.as2aas.com/v1/partners/prt_000001/test

Message Debugging

# Get message details
curl -H "Authorization: Bearer pk_test_your_key" \
     https://api.as2aas.com/v1/messages/msg_000001

# Check recent messages
curl -H "Authorization: Bearer pk_test_your_key" \
     "https://api.as2aas.com/v1/messages?per_page=5&sort=created_at:desc"

Certificate Validation

# List certificates with expiry information
curl -H "Authorization: Bearer pk_test_your_key" \
     https://api.as2aas.com/v1/certificates

# Validate specific certificate
curl -X POST \
     -H "Authorization: Bearer pk_test_your_key" \
     https://api.as2aas.com/v1/certificates/cert_000001/validate