FAQ & Troubleshooting

Account & Authentication

How do I reset my password?

If you signed up with an email and password, go to the login page and click Forgot Password. Enter your email address and Ocriva will send a reset link. The link is valid for a limited time — if it expires, request a new one.

If you signed up with Google OAuth, there is no separate Ocriva password to reset. Use your Google account's password recovery instead.

Can I use Google login?

Yes. On the sign-in page, click Continue with Google to authenticate using your Google account. Your Ocriva account is linked to your Google identity — you cannot set a separate email/password alongside it. If you originally signed up with email and want to link Google, sign in with your email account first and manage linked providers from your profile settings.

How do I switch organizations?

Click the organization name in the top-left of the dashboard to open the organization switcher. Select any organization you are a member of to switch to it. All pages — projects, documents, billing, analytics — reflect the currently active organization.

What happens if my session expires?

Ocriva uses short-lived JWT access tokens with a long-lived refresh token. When your access token expires, the platform automatically requests a new one using the refresh token — this happens silently in the background and you typically will not notice.

If the refresh token itself expires or is invalidated (for example, after a password change or signing out on another device), you will be redirected to the login page. Your work is not lost — documents, templates, and results are stored server-side.

Upload & Processing

What file types are supported?

Ocriva accepts the following formats for document processing:

• Images: PNG, JPEG/JPG, WebP, GIF
• Documents: PDF

What is the maximum file size?

The maximum size for a single uploaded file is determined by your organization's subscription plan. Refer to Organization → Limits to see your current storage and request limits. As a general guideline, files up to 20 MB are reliably supported.

For ticket and comment attachments specifically, the limit is 10 MB per file, with a maximum of 5 files per ticket or comment.

Why did my document fail to process?

The most common causes of processing failure are:

1. Insufficient credits — processing is blocked if the organization's credit balance cannot cover the cost of the selected AI model. Check your balance at Organization → Billing.
2. Unsupported file format — ensure the file is PNG, JPEG, WebP, GIF, or PDF.
3. Corrupt or unreadable file — if the PDF has DRM restrictions or the image is malformed, the AI cannot read it.
4. Template misconfiguration — if the template's AI model is no longer available or its credentials are not configured, processing will fail. Verify the model under Templates → Edit.
5. Storage bucket unavailable — if your organization's storage bucket is not accessible, uploads are rejected before processing begins. Contact support if this persists.

Failed documents are logged in Processing History with an error message. Click the record to expand it and read the exact error.

How long does processing take?

Processing time depends on the AI model selected in the template, document complexity, and current platform load. In typical conditions:

• Simple single-page images: 3–10 seconds
• Multi-page PDFs or complex forms: 15–60 seconds
• Batch jobs of 50+ files: several minutes total

You will receive an in-app notification when processing completes or fails. Real-time progress is visible in the Documents page while a job is running.

Can I process multiple documents at once?

Yes. Use the Batch Upload feature to upload and process multiple files in a single operation. Batch jobs track overall progress and allow you to export a combined result file (JSON or CSV) once all items are complete.

Navigate to Upload and select multiple files, or use the batch endpoint via the API. Each file in a batch is processed independently and credits are deducted per file.

Can Ocriva process scanned documents vs. digital PDFs?

Both work. The key difference is input quality:

• Scanned documents — Ocriva sends the image directly to the AI vision model. For reliable extraction, scans should be at least 150 DPI. Lower-resolution scans may cause the AI to misread characters or skip fields entirely. Make sure the document is not rotated or heavily skewed.
• Digital PDFs (PDFs created from software, not scanned) — these contain selectable text, which the AI can read with higher accuracy and at lower token cost. When possible, prefer digital PDFs over scanned images.

Can I process documents in multiple languages?

Yes. The underlying AI models (GPT-4o, Gemini, Claude) have multilingual capabilities. Thai and English are the most tested and best-supported languages on the platform. Arabic, Chinese, Japanese, and other major languages also work in most cases.

To improve accuracy for a specific language, add a language instruction to the template's System Prompt — for example: "The document is written in Thai. Extract all fields in their original language."

How do I export batch results?

Once a batch job finishes, open the batch from the Documents page and click Export. Two formats are available:

• JSON — a single combined file containing every document's structured extraction result.
• CSV — all rows merged into a flat spreadsheet, useful for importing into Excel or a database.

The export button is disabled while any item in the batch is still processing. Wait for all items to reach a completed or failed status before exporting.

See the Batch Processing guide for details on batch management and result structure.

Templates

What is a template and why do I need one?

A template tells Ocriva what data to extract from your documents and how to format the output. It defines:

• The extraction fields (for example: invoice number, date, vendor name, total amount)
• The AI model used to perform the extraction
• The output format (JSON, CSV, PDF, etc.)
• Optional system prompt and RAG data files for additional context

Every upload must be linked to a template. Without a template, the system does not know what to look for in your document.

How do I improve extraction accuracy?

Several factors affect how accurately the AI extracts data:

• Be specific in field definitions. A field named invoice_total_amount_thb gives the model more context than a field named total.
• Write a clear system prompt. Use the system prompt to describe the document type and any extraction rules specific to your use case.
• Add RAG data files. If your documents reference internal codes, product catalogs, or custom terminology, upload reference files as RAG data files so the model can use them for lookup.
• Choose the right AI model. For complex or low-quality documents, use a more capable model (GPT-4o, Claude) rather than a lighter one. For clean, structured documents, a lighter model (GPT-4o-mini, Gemini Flash) is usually sufficient and cheaper.
• Use high-resolution images. Blurry or low-contrast scans reduce extraction accuracy regardless of model choice.

Can I use different AI models for different templates?

Yes. Each template has its own AI model setting. You can have one template using GPT-4o for critical financial documents and another using Gemini Flash for routine receipts — all within the same project.

Available providers currently include OpenAI, Google Gemini, Anthropic Claude, DeepSeek, Qwen, and Kimi. The list of available models reflects which provider credentials are configured in your platform instance.

How do I test a template before production use?

Open the template in Templates → Edit and click the Test button in the toolbar. You can upload a sample document and the platform will run a live extraction using the current template configuration. The result is shown inline so you can compare extracted values against the document side by side.

Use the test run to:

1. Verify that all fields are being populated.
2. Identify fields with low-confidence or incorrect values.
3. Adjust field names, the system prompt, or RAG data files and re-test until accuracy is satisfactory.

What AI models are available and how do they compare?

The available models depend on the provider credentials configured in your platform instance. Common options and their typical trade-offs:

If you are not sure where to start, GPT-4o-mini offers a good balance of accuracy and cost for the majority of document types. Upgrade to GPT-4o for financial, legal, or otherwise critical documents where higher accuracy justifies the additional cost.

What is RAG / Data Files?

RAG (Retrieval-Augmented Generation) data files are reference documents you upload to a template. When the AI processes a document, it can retrieve relevant context from these files to improve accuracy.

Common uses include:

• Product catalogs (so the model can match product codes to names)
• Internal glossaries or abbreviation lists
• Country or currency code tables
• Custom validation rules

Data files are configured per template under Templates → Data Files. Supported formats are .json, .md (Markdown), and .txt (plain text).

Credits & Billing

How are credits deducted?

Credits are deducted per file processed, not per batch or API call. The cost depends on the AI model assigned to the template and is calculated from the token usage (prompt + completion tokens) multiplied by the model's per-token rate, converted to THB.

Package credits are consumed first; top-up credits are used after package credits are exhausted.

What happens when I run out of credits?

If your organization's credit balance reaches zero, all new processing requests are blocked. Existing results and uploaded files remain accessible. You can still view Processing History, manage templates, and access all other platform features — only new AI processing is blocked.

To restore processing, purchase additional credits via Organization → Billing.

Do credits expire?

It depends on the credit type:

• Top-up credits — never expire. They carry over indefinitely.
• Package credits — expire 30 days from the date of purchase. Unused package credits are forfeited at expiry.

When you have both types, package credits are always consumed first. Check the expiry date of your package credits in the Credit History section of the Billing page.

How do I get more credits?

Two options are available from Organization → Billing:

1. One-time top-up — purchase a fixed credit amount. Credits are added immediately after Stripe confirms payment and never expire.
2. Subscription package — subscribe to a monthly plan that adds a recurring credit allocation each billing period. Packages also unlock higher usage limits (storage, webhooks, templates, projects, API requests).

Both options go through Stripe checkout. No card data is stored on Ocriva servers.

API & Integration

How do I get an API token?

1. Go to Organization → API Tokens for organization-level tokens, or Project → API Tokens for project-scoped tokens.
2. Click Create Token.
3. Give the token a descriptive name (for example, "CI pipeline" or "ERP integration").
4. Copy the token immediately — it is only shown once. Store it securely.

API tokens are sent in the X-API-Key header on all requests to the OpenAPI endpoints.

What is the API rate limit?

Rate limits are enforced per API key and depend on your subscription package. The limit applies to the number of AI processing requests (tracked as maxRequestClassA). You can view current usage and limits at Organization → Limits.

If you exceed the rate limit, the API returns a 429 Too Many Requests response. Wait for the current window to reset before retrying.

How do I set up webhooks?

1. Go to Organization → Webhooks.
2. Click Add Endpoint and enter your HTTPS URL.
3. Select the event types you want to receive (for example: document.processed, document.failed, credit.added).
4. Save the endpoint.

Ocriva signs each webhook payload with an HMAC-SHA256 signature using a secret key shown when the endpoint is created. Verify the X-OCR-Signature header on your receiver to confirm authenticity.

See the Webhooks Guide for the full event list and verification code samples.

How do I debug a failed webhook delivery?

Go to Project → Webhooks and click on the endpoint you want to inspect. The Delivery Logs tab shows every delivery attempt with:

• HTTP status code returned by your endpoint
• Response body (truncated to the first 1 KB)
• Retry count — Ocriva retries failed deliveries with exponential backoff up to a configurable maximum

Common fixes:

• Ensure your endpoint URL is HTTPS. Plain HTTP endpoints are rejected.
• Confirm your server returns a 2xx status code within the timeout window. Timeouts count as failures.
• Check that your server is not filtering out Ocriva's IP range or user-agent.
• Verify the X-OCR-Signature header verification logic is not incorrectly rejecting valid payloads.

See the Webhooks Guide for the full retry schedule and signature verification examples.

Can I use the API without the SDK?

Yes. The Ocriva API is a standard REST API — any HTTP client works (curl, Postman, Python requests, etc.). You need two headers on every request:

• X-API-Key: <your-api-token> — authentication
• x-organization-id: <your-org-id> — organization context

Minimal curl example for uploading a document:

curl -X POST "https://api.ocriva.com/upload" \
  -H "X-API-Key: YOUR_TOKEN" \
  -H "x-organization-id: YOUR_ORG_ID" \
  -F "file=@invoice.pdf" \
  -F "templateId=TEMPLATE_ID" \
  -F "projectId=PROJECT_ID"

See the OpenAPI Overview for the full endpoint reference and request/response schemas.

What SDKs are available?

Ocriva provides a TypeScript/JavaScript SDK that wraps the OpenAPI endpoints. It handles authentication, request signing, error handling, and TypeScript types automatically.

See the SDK Getting Started guide for installation and usage instructions.

Common Errors

"Insufficient credits" — processing is blocked

Cause: The organization's credit balance is too low to cover the cost of the requested AI model.

Solution: Purchase more credits at Organization → Billing. Credits are added immediately after Stripe confirms payment.

If you believe your balance is incorrect, check the Credit History section — it logs every deduction and addition with timestamps and references.

"Organization bucket is not accessible"

Cause: The cloud storage bucket associated with your organization is unreachable — this can happen if bucket permissions changed or if the storage service is temporarily unavailable.

Solution: Retry the upload after a few minutes. If the error persists, open a support ticket under category Bug and include your organization ID. The Ocriva team can inspect the bucket configuration.

"Project validation failed" on upload

Cause: The projectId provided in the upload request is invalid, does not exist, or you are not a member of that project.

Solution: Confirm the projectId is correct by checking Organization → Projects. If you are using the API, ensure the project ID matches the organization specified in x-organization-id.

"Model not found" during processing

Cause: The AI model configured in the template is no longer registered in the platform's model registry, or the provider credentials for that model have been removed.

Solution: Edit the template (Templates → Edit) and select a different AI model from the available list. If the desired model is missing from the list entirely, the provider credentials need to be (re)configured by an administrator.

413 Payload Too Large

Cause: The uploaded file exceeds the size limit enforced by the server or your organization's plan.

Solution: Reduce the file size before uploading. For PDFs, try compressing the file or splitting a large multi-page document into smaller parts. For images, reduce resolution or export at a lower quality setting.

Check your organization's current file size limits at Organization → Limits. See the Limits & Quotas page for the full breakdown of size constraints by plan.

429 Too Many Requests

Cause: Your organization has exceeded its API request rate limit for the current window.

Solution: Wait for the rate-limit window to reset before sending additional requests. The Retry-After response header (when present) indicates how many seconds to wait.

For automated pipelines, implement an exponential backoff strategy: wait 1 second after the first 429, 2 seconds after the second, 4 seconds after the third, and so on.

See the Retry & Rate Limiting guide for recommended backoff patterns and header documentation.

"Template not found" during upload

Cause: The templateId provided in the upload request does not exist, has been deleted, or belongs to a different project than the one specified.

Solution:

1. Open Templates in the relevant project and confirm the template still exists.
2. Copy the template ID directly from the template's detail page to avoid typos.
3. Ensure the projectId and templateId in your request both belong to the same project — a template from Project A cannot be used for uploads in Project B.

"Credit was modified by another process" (transient error)

Cause: A race condition between two simultaneous processing requests competing for the same credit bucket. The system uses optimistic locking and automatically retries up to three times.

Solution: This error is usually resolved automatically. If you see it surfaced to the UI, wait a few seconds and resubmit. If it recurs consistently, it may indicate unusually high concurrent usage — contact support.