Troubleshooting
401 AUTH_ERROR
Causes
- Missing API key
- Invalid or revoked API key
- Using a dashboard-only route with an API key (e.g.
POST /api/tokens/lookuprequires a session; for shred usePOST /api/tokens/shredorDELETE /api/tokens/[id])
Fix
- Verify
Authorization: Bearer <key>orX-API-Key: <key> - Use the correct key for the environment (dev vs prod)
- For programmatic shred:
POST /api/tokens/shred(one token/mask) orPOST /api/tokens/shred-bulk(up to 1 000 ids or oneentityId; API key or session)
400 VALIDATION_ERROR
Cause: missing fields or invalid payload.
Fix: validate the body against HTTP Integration or the API Reference.
Common dataset upload messages:
| Message | Fix |
|---|---|
Missing file | Send multipart field file |
columnPolicies JSON string required | Pass columnPolicies as a JSON string in form data |
Missing policy for column "..." | Add a policy entry for every column |
Policy references unknown column "..." | Remove extra policy keys |
JSON dataset must be an array of objects | Fix JSON shape |
Too many cells (max N) | Reduce file size or split the import |
File exceeds max size (N bytes) | Split file or contact support for limit increase |
403 PLAN_LIMIT
Cause
- SaaS: plan quota exceeded (token creations lifetime, monthly request units, API keys, or datasets).
- On-premise: annual license quota exceeded for the current JWT period (
iat→exp) — token creations and/or request units. Alerts fire at 80% / 95% / 100%. Detokenize / lookup / shred / export stay available when only the request cap is hit; new tokenizations are blocked.
Fix
- Check dashboard usage (and Admin → Licence on-premise for consumed / limits)
- SaaS: upgrade on
/dashboard/billing, or use a MIGRATION API key for historical import - On-premise: contact Veilio for a quote amendment (Pro upgrade, extra instance, or custom quotas), then install the new JWT
403 PLAN_LIMIT_REACHED (organization invite)
Cause: member limit for plan (Starter = 1, Pro = 2).
Fix: upgrade to Pro or Enterprise, or contact Veilio for custom maxMembers.
403 FORBIDDEN (VIEWER role)
Cause: VIEWER role cannot tokenize, shred, or upload datasets.
Fix: ask OWNER/DPO for MEMBER role or API key whitelist.
408 TIMEOUT_ERROR
Cause: request exceeded server or client timeout (large bulk or format operations).
Fix
- Reduce batch size (
tokenize/bulk,detokenize/bulk) - Increase client timeout (SDK:
timeout/max_retries) - Retry with exponential backoff
410 TOKEN_SHREDDED
Cause: the token was cryptographically shredded (manual shred, retention TTL expired, or GDPR erasure).
Fix
- Do not retry detokenization — the plaintext is permanently destroyed
- Handle gracefully in your app (show "data no longer available")
- Create a new token if the user provides fresh data
SDK handling:
// JavaScript
import { TokenShreddedError } from "@veilio/sdk";# Python
from veilio_sdk import TokenShreddedError413 PAYLOAD_TOO_LARGE (datasets)
Cause: dataset file exceeds VEILIO_DATASET_MAX_BYTES (default 320 MB).
Fix: split the file into multiple uploads or contact support.
429 RATE_LIMIT_ERROR
Cause: too many requests in a short window.
Fix: honor Retry-After, use exponential backoff, prefer bulk endpoints. The official SDKs retry automatically.
Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.
500 INTERNAL_ERROR
Fix: retry with backoff; contact support@veilio.fr with timestamp, endpoint, and event_id if available from SIEM.
Migration mode errors
| Message | Fix |
|---|---|
| Migration not active | Activate from /dashboard/onboarding or POST /api/onboarding/migration |
| Budget exhausted | Increase allowance or contact support |
| Budget expired | Re-activate migration window |
| Freemium plan | Migration requires Starter/Pro/Enterprise |
Dataset access token errors
| Message | Fix |
|---|---|
Dataset not found | Check dataset ID and organization scope |
Dataset share keys cannot be used to import | Use a standard API key or dashboard for upload |
| Token expired | Generate a new access token (POST /api/datasets/[id]/access-token) |
Max TTL for dataset access tokens: 7 days. Default on upload: 48 hours.
On-premise license errors
| Symptom | Fix |
|---|---|
| Instance won't start, license expired > 30 days | Renew license on control plane |
| Read-only mode | License in grace period — renew before 30-day window ends |
| Auto-refresh fails | Check VEILIO_LICENSE_REFRESH_TOKEN and outbound HTTPS to control plane |
| Dashboard stuck on « Chargement… » after DB wipe / restore | Stale veilio_session cookie. Open /login (current images clear it and redirect with a relative /login) or clear site cookies, then sign in again |
After clear-stale, browser shows ERR_ADDRESS_INVALID or lands on the container listen address | Pull the current kit image (relative redirect). Or open /login on the public host once |
See Installation guide.
Stripe / billing (SaaS)
- Double charge risk: do not assign manual Enterprise in admin while a Stripe subscription is still active — cancel Stripe first.
- Org quotas wrong: ensure the org was created before Stripe checkout so
organizationIdis on the subscription row.