Troubleshooting

HTTP status codes

Symptom, likely cause and fix for each response
Code	Symptom	Likely cause	Fix
400	"'size' must be an integer between 1 and 512"	`size` is 0, over 512, or not a number; often someone passed a byte count (e.g. 32) thinking size is in bytes.	Use `size=1`; it returns 1,024 bytes. Slice 32 bytes for AES-256.
401	"Missing or malformed Authorization header"	No `Authorization` header, or it is not `Bearer <token>`. An empty `.env` value also causes this.	Send `Authorization: Bearer YOUR_TOKEN`. Check `.env` is in the folder you run from. Note: expired tokens are documented to return 401.
403	"Forbidden or entropy quota reached"	Either the token is wrong (live API returns 403, not 401, for a bad token) or the monthly quota is used up. An HTML "Error 1010" page instead means Cloudflare blocked your client's User-Agent.	Check the token first: no spaces or quotes, correct service (Entropy). Then check quota in the portal. For Error 1010, use `requests` or set a custom User-Agent; don't use Python's `urllib` defaults.
429	Too many requests	Rate limit. Docs say 30 requests per 10 seconds, but live can return 429 about 1 s after a single prior call (seen Oct 14, 2026). The API sends no `Retry-After` header.	Wait 10 s or more, then retry once. Never loop; request a larger `size` instead of many calls.
500	Internal error	Problem on Qrypt's side.	Try again shortly. If it persists, contact support@qrypt.com.
503	Entropy temporarily insufficient	Qrypt's entropy supply is briefly low.	Try again shortly, with a delay. Don't loop.

Retrying in a loop after a 429. Wait 10 s or more; live can rate-limit after one prior call.
Using the base64 string as the key instead of decoding it.
Treating size as bytes.
Reusing the same entropy bytes for two keys.
Printing the key or token while debugging, or committing .env.
Leaving out Accept: application/json (the docs require it).
Assuming an SDK package exists; the API is plain HTTPS.

Environment problems
Issue	Symptom	Cause	Fix
Runtime version	Node: `process.loadEnvFile is not a function` or `fetch is not defined`. Python: syntax errors.	Node older than 20.12, or Python older than 3.9.	Run `node -v` / `python3 --version` and upgrade.
Missing .env	"QRYPT_API_KEY is missing"	No `.env` in the current directory, or the variable name is misspelled.	Copy `.env.example` to `.env` in the folder you run from, or export `QRYPT_API_KEY`.
Missing packages	`ModuleNotFoundError: requests`	Dependencies not installed in the active environment.	`pip install -r requirements.txt` inside your virtualenv.
Proxy / TLS	`SSLError`, `CERTIFICATE_VERIFY_FAILED`, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `fetch failed`, or timeouts	Corporate proxy or TLS-inspecting firewall.	Python: `requests` honors `HTTPS_PROXY`; set `REQUESTS_CA_BUNDLE` to your company CA. Node: built-in `fetch` in Node 20 and 22 ignores `HTTPS_PROXY`. On Node 24+, run with `NODE_USE_ENV_PROXY=1` plus `HTTPS_PROXY`. On older Node, `npm i undici` and call `setGlobalDispatcher(new EnvHttpProxyAgent())` before `fetch`. Set `NODE_EXTRA_CA_CERTS` to your company CA. Never disable certificate checks.