Skip to main content
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

errors-import.ts

FileRouterError fields

message
string
A human-readable description of what went wrong. Suitable for logging, but use code for programmatic error handling.
code
FileRouterErrorCode
A stable string code identifying the category of error. See the full list of codes below.
providerId
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.
cause
unknown
The underlying error that triggered this FileRouterError, if any. Useful for debugging when a provider SDK throws an unexpected error.

Error codes

ProviderNotFound
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').
ProviderUnsupportedOutput
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.
ProviderUnavailable
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.
InvalidInput
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.
Auth
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.
RateLimit
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.
Timeout
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().
ParseFailed
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.
Unknown
FileRouterErrorCode
An unexpected error occurred that does not fit any other category. Check error.cause for the underlying error.

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.
error-handling.ts

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.
compare-error-check.ts
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).