Troubleshooting and Error Reference

While Volidator’s Zero-Knowledge architecture ensures strict data privacy, cryptographic systems can fail due to configuration mismatches or invalid keys. This guide details every common error code, its root cause, and how to fix it—whether you are a developer or using an AI coding assistant.

Ingestion API Error Codes Reference

When calling POST /v1/log, the Ingestion Worker will return specific HTTP status codes and JSON payloads on failure.

HTTP Status	Error JSON / Message	Cause	Resolution
`400`	`"Missing required fields: actorBlindIndex..."`	The request body is missing one or more of: `actorBlindIndex`, `actionBlindIndex`, `encryptedPayload`.	Ensure the client SDK is initializing correctly and all standard fields are present.
`401`	`"Unauthorized"`	Missing or malformed `Authorization` header.	Send the API key as a Bearer token: `Authorization: Bearer val_live_...`.
`401`	`"Invalid API Credentials"`	The API Key is structurally invalid, fails the CRC32 check, or is not registered in the D1 database.	Verify the key matches the format `val_live_[20-hex entropy][6-hex checksum]`. Check that the key hasn’t been revoked.
`429`	`"Too Many Requests - Rate Limit Exceeded"`	Ingestion rate limits exceeded for the client IP.	Implement an exponential backoff retry strategy in the client SDK. Contact sales to increase limits.

Common Cryptographic Failures

`AES-GCM decryption failed` / `Mac check failed`

Symptom: The dashboard logs table renders but shows a red error banner or blank entries.
Cause: The VOLIDATOR_ENCRYPTION_KEY in the browser URL hash fragment (#key) does not match the key used to encrypt the payload at ingestion time.
Fix: Check your active environment variables. If you rotated the key, you must provide the original key to decrypt historic logs, or re-encrypt your archive.

`Decryption key missing from hash context`

Symptom: The embeddable dashboard iframe is blank or shows a loading failure.
Cause: The iframe URL does not contain the # hash fragment containing the Data Encryption Key.
Fix: Verify your token generation logic. The generated URL must append the key as a hash: https://dash.volidator.com/embed/token#<KEY>. Note that the hash fragment is never transmitted over HTTP, keeping the key isolated to the browser.

SIEM Sync & DLQ Failures

Log Forwarding Retries

Symptom: Outbound logs are delayed in appearing on Datadog/Splunk.
Cause: The SIEM consumer encountered a transient networking error or rate limit from the SIEM provider.
Behavior: Volidator uses Cloudflare Queues with a single concurrent writer (max_concurrency: 1) to prevent D1 database lock contention.
Triage: If a bulk transaction fails, the consumer automatically retries each log sequentially. Clean logs are successfully written, while corrupted payloads are routed to the failed_logs Dead Letter Queue (DLQ) in D1.

AI Assistant / IDE Diagnostic Guide

If you are using an AI coding assistant (like Antigravity, Cursor, or Copilot) to debug Volidator integration issues, paste the error message along with the following context:

### Diagnostic Checklist for AI Tools
1. **API Key Checksum**: Is the key format `val_live_[a-f0-9]{26}`? Verify the last 6 characters match the CRC32 of the preceding 20.
2. **Key Placement**: Ensure `VOLIDATOR_ENCRYPTION_KEY` is kept client-side/in-env and never passed in HTTP request bodies (only in hash `#` fragments for widgets).
3. **Hydration postMessage**: Check if the parent window implements origin verification correctly matching the `?host` query parameter.

If the assistant needs to inspect database schemas, direct it to the standard Drizzle models located in packages/db/schema.ts.