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
string
A human-readable description of what went wrong. Suitable for logging, but use
code for programmatic error handling.FileRouterErrorCode
A stable string code identifying the category of error. See the full list of codes below.
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.unknown
The underlying error that triggered this
FileRouterError, if any. Useful for debugging when a provider SDK throws an unexpected error.Error codes
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').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.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.
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.
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.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.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().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.
FileRouterErrorCode
An unexpected error occurred that does not fit any other category. Check
error.cause for the underlying error.Handling errors in practice
Useinstanceof 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 callcompare(), 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