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