Reference
Troubleshooting, quick reference tables, system limits, usage analytics, and frequently asked questions.
Troubleshooting
Common issues and their solutions, organized by category. If your error is not listed here, check the Usage Log for the full error message and contact support.
Authentication & Credentials
Authentication failed (401)
Your API key is missing, expired, or invalid. Open the External Credential in Setup and verify the apiKey parameter contains a valid OpenRouter key (starts with sk-or-v1-). Regenerate the key at openrouter.ai/keys if needed.
Access denied (403)
Your OpenRouter account does not have access to the selected model. Upgrade your OpenRouter plan or select a different model.
Insufficient credits (402)
Your OpenRouter account has run out of credits. Add credits at openrouter.ai/credits.
Named credential not found
The Named Credential in Parsium Settings does not exist. Verify it is named Parsium_OpenRouter, or update the credential name in the Credentials tab.
Connection test fails with 'Unable to find named credential'
The credential name in Parsium Settings does not match any Named Credential in your org. Open the Credentials tab and select the correct one from the dropdown.
Extraction Issues
No field mappings found for [Object]
No field mappings are configured for the selected object. Go to Settings > Field Mapping, select the object, add fields, and click Save All.
API returned empty content
The AI model could not extract data from the uploaded file. Try a higher-quality file, a different model, or simpler field mapping instructions.
Request timed out
The file was too large or the model took too long. Reduce file sizes, upload fewer files, or switch to a faster model.
No matching record found for: [value]
A lookup field value does not match any Salesforce record by Name. Create the missing record manually or adjust your instruction.
Failed to parse extraction response
The AI returned a response Parsium could not parse as JSON. Try a more capable model or simplify your field mappings.
File Processing
File type not supported
Only specific formats are accepted. Check the File Types & Limits section in Extraction & Files for the full list.
Total file size exceeds maximum
The combined payload exceeds 4 MB. Upload fewer files or compress them.
Failed to extract text from DOCX/XLSX
The document may be corrupted or in a legacy format. Re-export as .docx or .xlsx and try again.
Model does not support this file type
The selected model does not support audio or video input. Use the capability filters in Model Selection to find a compatible model.
Rate Limiting & API
Rate limited (429)
Too many API calls. Parsium retries automatically up to 3 times with delays of 5s, 10s, and 15s. Wait a minute and try again.
Service temporarily unavailable (502/503)
OpenRouter or the upstream provider is temporarily down. Parsium retries automatically. Check status.openrouter.ai if it persists.
Context length exceeded
Your file(s) contain more text than the model can handle. Switch to a model with a larger context window (100k+ tokens) or upload a smaller file.
License & Quota
You have reached your monthly extraction limit
Your license quota is exhausted for the current period. Contact your administrator about upgrading, or wait for the next monthly reset.
Your Parsium license has expired
The license expiration date has passed. Contact Twilon support for renewal.
Your Parsium subscription has been suspended
The subscription has been deactivated. Contact Twilon support for reactivation.
User does not have a Parsium license
A named user license has not been assigned. Ask your admin to assign one from Setup > Installed Packages > Parsium > Manage Licenses.
Permissions & Access
Insufficient privileges
You are missing the Parsium_Admin or Parsium_User permission set. Ask your Salesforce administrator to assign it.
You do not have permission to access a related record
You lack read access to a lookup field's related object. Your admin needs to grant object-level or field-level permissions.
Field is not updateable
The mapped field is read-only (formula, auto-number, or system field). Remove it from your field mappings.
Object not appearing in Field Mapping dropdown
You need both read and update access to the object. Check your profile or permission set assignments.
External Credential Principal Access not working
Make sure you added the principal access to the correct permission set AND that the permission set is assigned to the user.
Quick Reference
Required Configuration Values
| Setting | Value |
|---|---|
| External Credential Label | Parsium Auth |
| External Credential Name | Parsium_Auth |
| Authentication Protocol | Custom |
| Principal Name | Parsium_Principal |
| Identity Type | Named Principal |
| Auth Parameter Name | apiKey |
| Auth Parameter Value | sk-or-v1-... (your OpenRouter key) |
| Named Credential Label | Parsium OpenRouter |
| Named Credential Name | Parsium_OpenRouter |
| Named Credential URL | https://openrouter.ai/api/v1 |
| Authorization Header | Bearer {!$Credential.Parsium_Auth.apiKey} |
Default Settings
| Setting | Default Value |
|---|---|
| AI Model | openai/gpt-4o |
| Temperature | 0 (Precise) |
| Privacy Level | 2 (Maximum) |
| Named Credential | Parsium_OpenRouter |
| Request Logging | Disabled |
| Reasoning Effort | Disabled (unless model requires it) |
Salesforce Objects
| Object | Type | Purpose |
|---|---|---|
Parsium_Settings__c | Hierarchy Setting | Stores org-level configuration (model, temperature, privacy, credential) |
Parsium_Field_Mapping__c | Custom Object | Stores field mapping definitions (object, field, instruction, active status) |
Parsium_Usage_Log__c | Custom Object | Tracks every extraction request with tokens, cost, timing, and status |
API Endpoints
| Endpoint | Method | Used For |
|---|---|---|
/chat/completions | POST | Main extraction (sends files + instructions, receives extracted data) |
/models | GET | Lists all available AI models for the model browser |
/endpoints/zdr | GET | Lists ZDR endpoints for Maximum privacy filtering |
External Links
- OpenRouter API KeysCreate and manage your API keys
- OpenRouter CreditsAdd credits to your OpenRouter account
- OpenRouter ModelsBrowse all available AI models and pricing
- OpenRouter StatusCheck for API outages and incidents
System Limits
Hard limits built into Parsium to keep extractions reliable within Salesforce's platform constraints.
| Limit | Value | Why |
|---|---|---|
| Max request payload | 4 MB | Salesforce HTTP callout body size limit |
| Max heap size | 6 MB | Salesforce Apex heap size governor limit |
| Max field mappings per object | 50 | Keeps prompts within token limits |
| Max instruction length | 500 characters | Prevents overly long prompts |
| Request timeout | 60s (120s for reasoning) | Salesforce callout timeout limit |
| Max retry attempts | 3 | Prevents infinite retry loops |
| Retry delays | 5s, 10s, 15s | Exponential backoff for rate limits |
| Temperature range | 0 to 2 | Standard AI model API range |
| Monthly extraction quota | Varies by license | Enforced per user based on license plan |
Usage & Analytics
Every extraction creates a Usage Log record. Parsium also ships with pre-built reports and a dashboard.
Usage Log Fields
| Field | What It Tracks |
|---|---|
| Status | Success or Error |
| Model Used | The AI model ID used for this extraction |
| Object API Name | Which Salesforce object was extracted to |
| Record ID | The specific record that was updated |
| Prompt Tokens | Number of input tokens |
| Completion Tokens | Number of output tokens |
| Total Tokens | Sum of prompt and completion tokens |
| Estimated Cost | Calculated cost in USD based on model pricing |
| Processing Time (ms) | How long the extraction took |
| Fields Updated | How many fields were successfully updated |
| Error Message | Error details if the extraction failed |
| Prompt Content | Full prompt (only if request logging is enabled) |
| File Names | Names of the uploaded files |
Built-in Reports
Usage Summary
Overview of total extractions, success rate, and token usage
Cost by Model
Compare spending across different AI models
Cost Trend
Track how extraction costs change over time
Latency by Model
Compare processing speeds across models
Token Efficiency
Analyze token usage relative to fields extracted
Success Rate
Track extraction success vs. failure over time
Error Analysis
Break down error types and their frequency
Usage by Object
See which Salesforce objects are extracted most
Usage by User
Track which users run the most extractions
Request History
Detailed log of every extraction request
Parsium also includes a Parsium Analytics dashboard that visualizes key metrics from these reports. Find it in the Dashboards tab in Salesforce.
FAQ
Frequently asked questions about Parsium.
How much does it cost to run an extraction?
The cost depends on the AI model you choose and the size of your files. Each model has different per-token pricing (shown in the Model Selection tab). A typical single-page invoice extraction with GPT-4o costs a fraction of a cent. You can monitor costs in the Usage Log and Cost by Model report.
Can I use Parsium with custom objects?
Yes. Any Salesforce object you have update access to will appear in the Field Mapping dropdown, including custom objects.
Is my data sent to OpenAI/Anthropic/Google directly?
Parsium sends data to OpenRouter, which routes it to the AI provider of the model you selected. At the Maximum privacy level, only ZDR (Zero Data Retention) endpoints are used, meaning the provider never stores your data.
Can I use my own OpenAI/Anthropic API key instead of OpenRouter?
No. Parsium is built to work with OpenRouter, which provides a single gateway to all major AI providers through one API key and one Named Credential.
What happens if the extraction gets a value wrong?
You can review extracted values before applying them. If a value is incorrect, do not apply it. Improve your field mapping instruction to be more specific.
Can I run extractions in bulk (multiple records at once)?
The extraction wizard processes one record at a time. For bulk processing, you can build a Salesforce Flow that calls the Parsium Apex methods programmatically.
What happens when a lookup field's related record does not exist?
Parsium searches for the record by Name. If no match is found, the extraction result will show a 'No matching record found' message for that field. Other fields will still be extracted normally.
How do I change the AI model after initial setup?
Go to Parsium Settings > Model Selection tab, browse or search for the model you want, and click to select it. The change takes effect on the next extraction.
Can multiple users run extractions at the same time?
Yes. Each extraction is an independent API call. Multiple users can run extractions simultaneously without conflicts.
Does Parsium work in Salesforce sandboxes?
Yes. Install and configure Parsium in your sandbox the same way as production. You will need to create a Named Credential separately (credentials are not copied between environments).