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 Request Log for the full error message and contact support.
Authentication & Connection
Authentication failed (401)
Your API key is missing, expired, or invalid. Disconnect and reconnect to OpenRouter through the OAuth flow in Parsium Settings. This generates a fresh API key.
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/settings/credits.
OpenRouter is not connected
No API key is stored. Open Parsium Settings and complete the Connect to OpenRouter wizard (OAuth flow).
Connection test fails
The stored API key may be expired or revoked. Ask the owner to disconnect and reconnect through the OAuth flow.
Invalid PIN
The PIN you entered does not match. Try again. If you forgot your PIN, use your recovery code to reset it. If you lost both, contact support@twilon.com for a remote reset.
You are not an owner
Only owners can access the Configuration sub-tab. Ask an existing owner to add you as a co-owner from the Access Management section.
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.
Parsium Insight
No Insight model configured
No Insight model has been selected. Go to Settings > Model and select an Insight model. This is separate from the extraction model.
Briefing generation failed
The AI request failed during briefing generation. Retry, or switch to a different Insight model. Check Usage Logs for details.
Insight requires Parsium Professional
Parsium Insight (AI record briefings and document Q&A) is a Professional-tier feature. Ask your administrator to assign the Parsium_Professional_User permission set.
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 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 progressive delays of 200ms, 400ms, and 600ms. Wait a moment 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
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.
Feature Tier (Starter vs Professional)
Audio file processing requires Parsium Professional
Audio file uploads are a Professional-tier feature. Ask your administrator to assign the Parsium_Professional_User permission set, or use document and image formats instead.
Voice recording requires Parsium Professional
Live voice dictation is a Professional-tier feature. Ask your administrator to upgrade your permission set to Parsium_Professional_User.
Child record extraction requires Parsium Professional
Extracting and creating child records (e.g., Contacts from an Account document) is a Professional-tier feature. Upgrade to Parsium_Professional_User to enable it.
CSV import/export requires Parsium Professional
Bulk CSV import and export of field mappings is a Professional-tier feature. Ask your administrator to assign the Parsium_Professional_User permission set.
Permissions & Access
Insufficient privileges
You are missing a Parsium permission set. Ask your Salesforce administrator to assign Parsium_Admin, Parsium_Professional_User, or Parsium_User depending on your role.
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). Parsium automatically skips non-editable fields before extraction and shows them in a collapsible banner. Remove the mapping if the field should not be extracted.
Object not appearing in Field Mapping dropdown
You need both read and update access to the object. Check your profile or permission set assignments.
Cannot remove the last owner
You cannot remove the last remaining owner. Add another owner first, or disconnect from OpenRouter entirely.
Quick Reference
Connection Details
| Setting | Value |
|---|---|
| Authentication Method | OAuth PKCE (automated) |
| Credential Storage | Protected Custom Setting (Parsium_Credentials__c) |
| API Base URL | https://openrouter.ai/api/v1 |
| PIN Format | 4-6 digit numeric |
| PIN Storage | SHA-256 hash + random salt |
| Recovery Code Format | PRSM-XXXX-XXXX-XXXX (16 chars) |
| Audit Retention | 90 days minimum (immutable) |
| Owner Identity | User IDs in Protected Custom Setting |
Default Settings
| Setting | Default Value |
|---|---|
| AI Model | openai/gpt-4o |
| Privacy Level | 2 (Maximum) |
| Request Logging | Disabled |
| Reasoning Effort | Disabled (unless model requires it) |
| Analytics Retention | 90 days |
Salesforce Objects
| Object | Type | Purpose |
|---|---|---|
Parsium_Settings__c | Hierarchy Setting | Stores org-level configuration (extraction model, Insight model, privacy level, analytics settings) |
Parsium_Credentials__c | Protected Hierarchy Setting | Stores API key, management key, PIN and recovery hashes, and owner user IDs. Invisible to Salesforce admins. |
Field_Mapping__c | Custom Object | Stores field mapping definitions (object, field, instruction, active status) |
Request_Log__c | Custom Object | Tracks every extraction and briefing request with tokens, cost, timing, and status |
Audit_Log__c | Custom Object | Immutable record of every configuration change (model, privacy, owner, PIN events) |
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 | 200ms, 400ms, 600ms | Progressive backoff for rate limits |
| Max child object types per extraction | 5 | Keeps prompt scope manageable |
| Max child records per object type | 50 | Governor limit protection |
| Max child records per briefing | 10 | Limits briefing prompt scope |
| Brief briefing max tokens | 256 | Controls brief briefing response length |
| Standard briefing max tokens | 512 | Controls standard briefing response length |
| Detailed briefing max tokens | 1,536 | Controls detailed briefing response length |
| Audit log retention | 90 days | Minimum immutable retention period for audit records |
| PIN length | 4-6 digits | Numeric only, stored as SHA-256 hash |
Usage & Analytics
Every extraction creates a Request Log record. Parsium also ships with pre-built reports and a dashboard.
Request 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 |
| Routing Type | Whether the request went through OpenRouter |
| Request Type | Type of operation: Extraction, Briefing, or Briefing (Extended) |
| Fields Extracted | Number of fields the AI successfully extracted |
| Fields Accepted | Number of extracted fields the user accepted |
| Fields Rejected | Number of extracted fields the user rejected |
| Accuracy Rate | Calculated: Fields Accepted / Fields Extracted (formula) |
| Cost Per Field | Calculated: Estimated Cost / Fields Extracted (formula) |
Built-in Reports
Usage Summary
Overview of total extractions, success rate, and key metrics
Cost Trends
Track how extraction costs change over time
Cost by Model
Compare spending across different AI models
Usage by User
Track which users run the most extractions
Usage by Object
See which Salesforce objects are extracted most
Model Comparison
Compare performance across different AI models
Cost Efficiency
Analyze cost per field and cost effectiveness
Error Detail
Break down error types and their frequency
Accuracy by Object
Track extraction accuracy rates per object
Request History
Detailed chronological log of every 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 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 AI providers 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 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 OAuth connection.
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 > OpenRouter > Configuration > Model & Parameters. Browse or search for the model you want and click to select it. You will need to enter your PIN. 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 connect to OpenRouter separately (credentials are not copied between environments).
What is a Parsium owner and how is it different from an admin?
An owner is the person who connected OpenRouter. Owner identity is stored in a Protected Custom Setting, invisible to Salesforce admins. Owners control sensitive settings (model, privacy, connection) with PIN authorization. Admins (Parsium_Admin permission set) manage field mappings and view status. An admin who also connects OpenRouter becomes an owner.
I forgot my PIN. How do I reset it?
Use your recovery code (the PRSM-XXXX-XXXX-XXXX code shown during setup) to reset your PIN. If you lost your recovery code too, contact support@twilon.com. Twilon support can trigger a remote PIN reset through the License Management App.
Can a Salesforce admin access or change my API key?
No. API keys are stored in a Protected Custom Setting (Parsium_Credentials__c), which is invisible and inaccessible to subscriber admins. Only Parsium's managed Apex code can read the stored credentials. Even Salesforce system administrators cannot view or query these values.
What is the difference between Starter and Professional?
Starter includes core document extraction (images, PDFs, DOCX, XLSX, CSV, text files), lookup resolution, context-aware extraction, and the review workflow. Professional adds voice recording, audio file processing, Parsium Insight (AI record briefings and document Q&A), child record creation, multi-record updates, and CSV bulk mapping operations.