When integrating OpenAI with Metorial, proper error handling ensures your application remains robust and provides good user experiences.

Common Error Scenarios

API Key Issues

try {
  await metorial.withProviderSession(
    metorialOpenAI.chatCompletions,
    { serverDeployments: ['your-deployment'] },
    async session => {
      // Your code here
    }
  );
} catch (error) {
  if (error.message.includes('authentication') || error.message.includes('api key')) {
    console.error('Invalid API key. Please check your credentials.');
  }
}

Tool Call Failures

The Metorial SDK handles tool call errors gracefully by returning error messages instead of throwing:

let toolResponses = await session.callTools(toolCalls);
// Tool errors are included in the response, not thrown
// OpenAI will see the error message and can respond appropriately

Rate Limiting

try {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages,
    tools: session.tools
  });
} catch (error) {
  if (error.status === 429) {
    console.error('Rate limit exceeded. Please wait before retrying.');
    // Implement exponential backoff here
  }
}

Complete Error Handling Example

import { Metorial } from 'metorial';
import { metorialOpenAI } from '@metorial/openai';
import OpenAI from 'openai';

async function chatWithTools(userMessage: string) {
  const metorial = new Metorial({
    apiKey: process.env.METORIAL_API_KEY
  });

  const openai = new OpenAI({
    apiKey: process.env.OPENAI_API_KEY
  });

  try {
    await metorial.withProviderSession(
      metorialOpenAI.chatCompletions,
      { serverDeployments: ['your-deployment'] },
      async session => {
        try {
          const messages = [{ role: 'user', content: userMessage }];

          const response = await openai.chat.completions.create({
            model: 'gpt-4o',
            messages,
            tools: session.tools
          });

          const toolCalls = response.choices[0]?.message.tool_calls;
          
          if (toolCalls) {
            const toolResponses = await session.callTools(toolCalls);
            // Errors from tools are handled internally
            
            messages.push(
              { role: 'assistant', tool_calls: toolCalls },
              ...toolResponses
            );

            const finalResponse = await openai.chat.completions.create({
              model: 'gpt-4o',
              messages,
              tools: session.tools
            });

            return finalResponse.choices[0]?.message.content;
          }

          return response.choices[0]?.message.content;
          
        } catch (openaiError) {
          console.error('OpenAI API error:', openaiError);
          throw new Error('Failed to get response from OpenAI');
        }
      }
    );
  } catch (metorialError) {
    console.error('Metorial error:', metorialError);
    throw new Error('Failed to connect to Metorial');
  }
}

Best Practices

• Always wrap API calls in try-catch blocks
• Log errors for debugging but don't expose sensitive details to users
• Implement retry logic with exponential backoff for rate limits
• Provide helpful error messages to users
• Monitor errors in production to identify patterns