Error Handling & Setup

Overview

This guide covers error responses, credential configuration, and troubleshooting for the External Service Proxy API.

Developer

---

Error Responses

The External Service Proxy API returns standard HTTP status codes with JSON error details.

404 Not Found

Service or endpoint not found:

{
  "detail": "External proxy service 'unknown' not found or disabled."
}

Causes:

• The service slug is incorrect or the service is not enabled
• The endpoint/action slug is invalid
• The service has been disabled in the platform configuration

Solution:

• Use the Service Discovery endpoints to get valid service and endpoint slugs
• Verify the service is enabled in your organization settings
• Check for typos in service or action names

---

Credentials not configured:

{
  "detail": "No allowed credentials found for external proxy service 'elevenlabs'."
}

Causes:

• No credentials have been configured for the service
• Credentials exist but are not accessible due to policy restrictions

Solution:

• Configure credentials via the admin panel (see Setting Up Credentials)
• Verify credential policy allows your organization to use the credentials
• Check that credentials are properly saved and active

---

400 Bad Request

Invalid request or credential policy error:

{
  "error": "Credential policy does not allow any credential source."
}

Causes:

• The credential policy configuration is invalid
• Required path parameters are missing
• Request body format is incorrect

Solution:

• Verify all required path_params are provided (extract from path_template)
• Ensure request body matches the expected format
• Check the credential policy configuration in admin settings

---

Missing path parameters:

{
  "error": "Missing required path parameter: voice_id"
}

Causes:

• Required path parameters from the path_template were not provided in path_params

Solution:

• Parse the endpoint's path_template to identify required parameters
• Include all parameters in the path_params field
• See Understanding Path Templates for details

---

502 Bad Gateway

Upstream service error:

{
  "detail": "The upstream external service request failed."
}

Causes:

• The external service (ElevenLabs, HeyGen, etc.) returned an error
• Network issues connecting to the external service
• Invalid credentials provided to the upstream service
• Rate limiting or quota exceeded on the external service

Solution:

• Check the external service's status page for outages
• Verify your credentials are valid and have sufficient quota
• Review the request payload for errors in the body field
• Check if you've exceeded the external service's rate limits
• Wait and retry the request (implement exponential backoff)

---

401 Unauthorized

Authentication failed:

{
  "detail": "Authentication credentials were not provided."
}

{
  "detail": "Invalid token."
}

Causes:

• Missing Authorization header
• Invalid API key or token
• Expired token

Solution:

• Include the Authorization header in your request
• Verify your API key or token is correct
• Generate a new API key if needed
• Check token expiration and refresh if necessary

---

403 Forbidden

Permission denied:

{
  "detail": "You do not have permission to perform this action."
}

Causes:

• User lacks necessary permissions
• Organization does not have access to the service
• Feature not enabled for your plan

Solution:

• Verify your user role has the required permissions
• Contact your administrator to enable the service
• Check your organization's plan and feature access

---

Setting Up Credentials

Credentials must be configured for each service before you can use the External Service Proxy API. This is typically done by platform administrators.

Credential Configuration Table

Configuration Steps

1. Obtain API credentials from the external service:

   • Log in to the external service's platform
   • Navigate to API settings or developer settings
   • Generate a new API key if needed
   • Copy the API key securely

2. Configure credentials in the platform:

   • Log in to the admin panel
   • Navigate to External Service settings
   • Select the service (e.g., ElevenLabs, HeyGen)
   • Enter the credential information in the required format
   • Save the configuration

3. Test the credentials:

   • Use a simple list endpoint to verify connectivity
   • Example: Call list-voices for ElevenLabs or list-avatars for HeyGen
   • If successful, the credentials are properly configured

Credential Policy

Each service has a credential policy that determines how credentials are resolved:

Example credential policy:

{
  "allow_tenant_key": true,
  "allow_platform_key": true,
  "default_source": "tenant",
  "fallback_to_platform_key": true
}

This policy means:

1. Try to use tenant-specific credentials first
2. If tenant credentials are not found, fall back to platform credentials
3. Both credential sources are allowed

---

Troubleshooting

Issue: "Service not found or disabled"

Symptoms:

• 404 error when calling any endpoint for a service
• Service doesn't appear in the discovery list

Solutions:

1. Check if the service is enabled in platform settings
2. Verify you're using the correct service slug
3. Use the List Services endpoint to see available services
4. Contact administrator to enable the service

---

Issue: "No credentials found"

Symptoms:

• 404 error mentioning credentials
• Service appears in discovery but endpoints fail

Solutions:

1. Configure credentials for the service (see Setting Up Credentials)
2. Verify credential policy allows your organization
3. Check that credentials are active and not expired
4. Test credentials directly with the external service

---

Issue: "Upstream request failed"

Symptoms:

• 502 Bad Gateway errors
• Intermittent failures

Solutions:

1. Check external service status page for outages
2. Verify your credentials with the external service directly
3. Check if you've hit rate limits or quota
4. Review request payload for errors
5. Implement retry logic with exponential backoff
6. Contact external service support if issues persist

---

Issue: "Missing path parameter"

Symptoms:

• 400 error mentioning missing parameters
• Requests fail with path parameter errors

Solutions:

1. Parse the endpoint's path_template to identify required params
2. Include all parameters in the path_params field
3. Use the dynamic client which validates parameters automatically
4. Check the endpoint documentation for parameter requirements

---

Issue: "Rate limiting"

Symptoms:

• 429 Too Many Requests errors
• Requests failing after many successful calls

Solutions:

1. Implement rate limiting on your side
2. Add retry logic with exponential backoff
3. Check your external service plan limits
4. Upgrade your external service plan if needed
5. Cache responses when possible to reduce API calls

---

Issue: "Response type mismatch"

Symptoms:

• Error parsing JSON when expecting audio/video
• Blob when expecting JSON

Solutions:

1. Check the endpoint's response_mode in service details
2. Use appropriate response handling based on mode
3. Implement response mode handling
4. Check Content-Type header in the response
5. Use the dynamic client which handles response types automatically

---

Best Practices

1. Error Handling

Always implement proper error handling:

async function safeInvoke(client, service, action, payload) {
  try {
    return await client.invoke(service, action, payload);
  } catch (error) {
    if (error.message.includes('404')) {
      console.error('Service or endpoint not found:', service, action);
      // Handle missing service/endpoint
    } else if (error.message.includes('502')) {
      console.error('Upstream service failed, retrying...');
      // Implement retry logic
    } else if (error.message.includes('credentials')) {
      console.error('Credentials not configured');
      // Alert administrator
    } else {
      console.error('Unexpected error:', error);
    }
    throw error;
  }
}

2. Retry Logic

Implement exponential backoff for transient failures:

async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 1000) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;

      const delay = baseDelay * Math.pow(2, i);
      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

3. Credential Validation

Test credentials before production use:

async function validateCredentials(client, service) {
  try {
    // Try a simple list endpoint
    if (service === 'elevenlabs') {
      await client.invoke('elevenlabs', 'list-voices', {});
    } else if (service === 'heygen') {
      await client.invoke('heygen', 'list-avatars', {});
    }
    console.log(`${service} credentials valid`);
    return true;
  } catch (error) {
    console.error(`${service} credentials invalid:`, error);
    return false;
  }
}

4. Logging

Log important events for debugging:

class LoggingProxyClient extends ExternalProxyClient {
  async invoke(serviceSlug, actionSlug, payload = {}) {
    console.log(`[ProxyAPI] Invoking ${serviceSlug}/${actionSlug}`);
    const startTime = Date.now();

    try {
      const result = await super.invoke(serviceSlug, actionSlug, payload);
      const duration = Date.now() - startTime;
      console.log(`[ProxyAPI] Success in ${duration}ms`);
      return result;
    } catch (error) {
      const duration = Date.now() - startTime;
      console.error(`[ProxyAPI] Failed after ${duration}ms:`, error.message);
      throw error;
    }
  }
}

---

Related Pages

• Overview - Authentication and service discovery
• Integration Guide - Path templates and dynamic client
• ElevenLabs Integration - Text-to-speech endpoints
• HeyGen Integration - Video generation endpoints