If the API request encounters an unrecoverable error during parsing (either from the client-side or server-side), the library includes an errors field in the final result for the affected pages.

Each error contains the error message, error_code, and corresponding page number.

​
Error Message: Illegal header value b’Basic ’

You may see the following error when calling the API:

[error  ] Error parsing document 'File name: file_namePage: #:#]' due to: Illegal header value b'Basic ' [agentic_doc.parse] (parse.py:246)

This error typically means that the API key is missing, not set correctly, or being read too late in your code. Get your API key on the API Key page.

Use the tips below to help you resolve the error.

​
1. Make Sure Your API Key Is Set

The most common cause of this error is that the API key was not found when the library was initialized.

If you’re using the library, try setting the API key before importing the library. For example, in the snippet below, the API key is set in the VISION_AGENT_API_KEY environment variable before importing anything from the library.

import os
# Set environment variable first
os.environ["VISION_AGENT_API_KEY"] = "your_api_key_here"

# Now import the library
from agentic_doc.parse import parse_documents

​
2. Check That the Environment Variable Is Not Empty

Sometimes, the environment variable might be blank or incorrectly set. Run one of the following commands to verify. If the output is empty, you’ll need to set the environment variable again.

Windows (PowerShell)

echo $env:VISION_AGENT_API_KEY

macOS, Linux, Google Colab

echo $VISION_AGENT_API_KEY

​
3. Do Not Add the “Basic” Prefix

The library automatically handles the correct formatting for authorization. Do not include Basic in your API key. Just use the raw key as provided.

Incorrect

os.environ["VISION_AGENT_API_KEY"] = "Basic sk-abc123..."  # Don't do this

Correct

os.environ["VISION_AGENT_API_KEY"] = "sk-abc123..."  # Use the plain key

​
4. Set API Key Using the Library Settings

If you prefer not to use environment variables or want more control, you can set the API key using the config module. This approach is also useful in environments where setting environment variables is difficult or not persistent (notebooks, scripts run via cron, etc.).

For example:

from agentic_doc.config import settings
settings.vision_agent_api_key = "your_api_key_here"