# Error handling
URL: https://metorial.com/docs/build/sdk/error-handling

Handle errors gracefully in your Metorial SDK applications

---

<PageIntro>
  <Learn>
    * Common error types
    * Error handling patterns
  </Learn>
</PageIntro>

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 [#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.

<CodeBlockTabs defaultValue="TypeScript" mode="code">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="TypeScript">
      TypeScript
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="TypeScript">
    ```typescript
    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}`);
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Python">
    ```python
    from metorial import (
        Metorial,
        AuthenticationError,
        NotFoundError,
        RateLimitError,
        OAuthRequiredError,
    )
    import os

    metorial = Metorial(api_key=os.getenv("METORIAL_API_KEY"))

    try:
        async with metorial.provider_session(
            provider="openai",
            providers=[{"provider_deployment_id": "your-provider-deployment-id"}],
        ) as session:
            tools = session.tools
    except AuthenticationError:
        # Invalid API key
        print("Check your METORIAL_API_KEY")
    except NotFoundError:
        # Deployment doesn't exist or not accessible
        print("Deployment not found - verify your deployment ID")
    except OAuthRequiredError:
        # Server requires OAuth but no session was provided
        print("This server requires OAuth - see the OAuth section above")
    except RateLimitError:
        # Too many requests
        print("Rate limited - try again later")
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<HeadsUp title="Common errors">
  The error types you are most likely to hit, and how to recover from each.

  <Definitions>
    <Definition term="AuthenticationError">
      You have provided an invalid Metorial API key.
    </Definition>

    <Definition term="NotFoundError">
      The deployment ID doesn't exist or you don't have access to it. Double-check your
      deployment ID in the Metorial dashboard.
    </Definition>

    <Definition term="OAuthRequiredError">
      The user's OAuth authorization has expired. Prompt them to re-authorize through the
      OAuth flow.
    </Definition>

    <Definition term="RateLimitError">
      You're making too many requests. Implement exponential backoff and respect rate limit
      headers.
    </Definition>
  </Definitions>
</HeadsUp>