> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filerouter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle FileRouter SDK Errors Gracefully

> Every FileRouter SDK error is a FileRouterError instance. Catch it with instanceof and branch on the code field for auth, rate-limit, and timeout errors.

Every error thrown by the FileRouter SDK is an instance of `FileRouterError`. This gives you a single `instanceof` check and a typed `code` field to branch on, instead of pattern-matching on error messages. You can import `FileRouterError` directly from `@file_router/sdk`.

## Import

```ts errors-import.ts theme={null}
import { FileRouterError } from '@file_router/sdk'
```

## FileRouterError fields

<ResponseField name="message" type="string">
  A human-readable description of what went wrong. Suitable for logging, but use `code` for programmatic error handling.
</ResponseField>

<ResponseField name="code" type="FileRouterErrorCode">
  A stable string code identifying the category of error. See the full list of codes below.
</ResponseField>

<ResponseField name="providerId" type="string | undefined">
  The ID of the provider that caused the error (e.g. `'llamaparse'`, `'mistral-ocr'`). Present when the error is directly attributable to a specific provider. `undefined` for SDK-level errors like `InvalidInput` or `Auth`.
</ResponseField>

<ResponseField name="cause" type="unknown">
  The underlying error that triggered this `FileRouterError`, if any. Useful for debugging when a provider SDK throws an unexpected error.
</ResponseField>

## Error codes

<ResponseField name="ProviderNotFound" type="FileRouterErrorCode">
  No provider with the requested ID is configured in this `FileRouter` instance. Check that the provider ID string matches a key in your `providers` map exactly (e.g. `'mistral-ocr'`, not `'mistral'`).
</ResponseField>

<ResponseField name="ProviderUnsupportedOutput" type="FileRouterErrorCode">
  The requested output type is not supported by the selected provider. This error is thrown before any file is sent to the provider. Check the provider's documented capabilities and remove the unsupported output from your `outputs` array.
</ResponseField>

<ResponseField name="ProviderUnavailable" type="FileRouterErrorCode">
  The provider returned an unrecoverable error during processing. This is distinct from a transient failure — the provider actively rejected the request or reported an internal error.
</ResponseField>

<ResponseField name="InvalidInput" type="FileRouterErrorCode">
  The document input could not be resolved. This can happen when a local file path does not exist, a stream has already been consumed, or the input value is in an unexpected format.
</ResponseField>

<ResponseField name="Auth" type="FileRouterErrorCode">
  An API key is missing or invalid. For the hosted client, check that `FILEROUTER_API_KEY` is set. For BYOK mode, verify that the relevant provider environment variable (`LLAMA_CLOUD_API_KEY`, `MISTRAL_API_KEY`, etc.) is set correctly.
</ResponseField>

<ResponseField name="RateLimit" type="FileRouterErrorCode">
  Your request hit a rate limit from the provider or the FileRouter hosted service. Back off and retry after a delay. Consider using `idempotencyKey` on hosted calls so retrying the same logical job is safe.
</ResponseField>

<ResponseField name="Timeout" type="FileRouterErrorCode">
  The job did not complete within the allowed time window. The default timeout is 10 minutes (600 000 ms). You can adjust this with the `timeoutMs` option on `parse()` or `compare()`.
</ResponseField>

<ResponseField name="ParseFailed" type="FileRouterErrorCode">
  The provider returned a failed status for the parse job. The document was accepted but could not be processed — for example, a password-protected PDF or a format the provider does not support at runtime.
</ResponseField>

<ResponseField name="Unknown" type="FileRouterErrorCode">
  An unexpected error occurred that does not fit any other category. Check `error.cause` for the underlying error.
</ResponseField>

## Handling errors in practice

Use `instanceof FileRouterError` to distinguish SDK errors from other runtime errors, then switch on `error.code` to handle specific failure modes.

```ts error-handling.ts theme={null}
import { FileRouter, FileRouterError } from '@file_router/sdk'
import { llamaparse } from '@file_router/sdk/llamaparse'

const router = new FileRouter({
  providers: { llamaparse: llamaparse() },
})

try {
  const result = await router.parse('https://example.com/report.pdf', {
    provider: 'llamaparse',
    outputs: ['markdown'],
  })
  console.log(result.outputs.markdown)
} catch (error) {
  if (error instanceof FileRouterError) {
    switch (error.code) {
      case 'Auth':
        console.error('Missing or invalid API key. Check LLAMA_CLOUD_API_KEY.')
        break
      case 'RateLimit':
        console.error('Rate limit hit — back off and retry.')
        break
      case 'Timeout':
        console.error('Parse job timed out. Try increasing timeoutMs.')
        break
      case 'ParseFailed':
        console.error(`Parse failed (provider: ${error.providerId}):`, error.message)
        break
      case 'ProviderUnsupportedOutput':
        console.error(`Output not supported by ${error.providerId}:`, error.message)
        break
      default:
        console.error(`FileRouter error [${error.code}]:`, error.message, error.cause)
    }
  } else {
    // Something unexpected — rethrow
    throw error
  }
}
```

## Errors inside compare results

When you call `compare()`, provider failures do not throw — they appear as entries with `status: 'failed'` or `status: 'unsupported'` in the `CompareResult.providers` array. You only receive a thrown `FileRouterError` from `compare()` itself if the input cannot be resolved or the entire operation times out.

```ts compare-error-check.ts theme={null}
const comparison = await router.compare('https://example.com/invoice.pdf', {
  outputs: ['markdown'],
})

for (const entry of comparison.providers) {
  if (entry.status !== 'parsed') {
    console.warn(
      `Provider ${entry.provider} ${entry.status}:`,
      entry.error?.code,
      entry.error?.message
    )
  }
}
```

<Tip>
  When a `compare()` entry fails, `entry.error.code` contains the same `FileRouterErrorCode` string you'd find on a thrown `FileRouterError`. You can use it to determine whether the failure was a misconfiguration (`ProviderNotFound`, `ProviderUnsupportedOutput`) or a runtime error (`ParseFailed`, `ProviderUnavailable`).
</Tip>