Error Handling

Handle errors gracefully in your Metorial SDK applications

What you’ll learn:

• Common error types
• Error handling patterns
• Debugging tips

The Metorial SDK throws typed errors that help you identify and handle specific failure scenarios. All API-related errors are instances of MetorialAPIError, which includes the error message, HTTP status code, and error type.

Catching Errors

Wrap your Metorial SDK calls in try-catch blocks to handle errors gracefully. Check if the error is a MetorialAPIError to access structured error information.

TypeScript

import { MetorialAPIError } from 'metorial';

try {
    await metorial.withProviderSession(
        provider,
        { serverDeployments: [{ serverDeploymentId: 'dep_123' }] },
        async ({ tools, closeSession }) => {
            // Your logic
            await closeSession();
        }
    );
} catch (error) {
    if (error instanceof MetorialAPIError) {
        console.error(`API Error: ${error.message}`);
    }
}

Common Errors

Here are the most common error types you’ll encounter and how to handle them:

AuthenticationError: You have provided an invalid Metorial API key.

NotFoundError: The deployment ID doesn’t exist or you don’t have access to it. Double-check your deployment ID in the Metorial dashboard.

OAuthRequiredError: The user’s OAuth authorization has expired. Prompt them to re-authorize through the OAuth flow.

RateLimitError: You’re making too many requests. Implement exponential backoff and respect rate limit headers.