Error handling

What you'll learn

Common error types
Error handling patterns

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.

import { MetorialAPIError } from 'metorial';

try {
    await metorial.withProviderSession(
        provider,
        { providers: [{ providerDeploymentId: 'pdp_123' }] },
        async session => {
            // Your logic
        }
    );
} catch (error) {
    if (error instanceof MetorialAPIError) {
        console.error(`API Error: ${error.message}`);
    }
}

Common errors

The error types you are most likely to hit, and how to recover from each.

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.