Errors

Every error body is JSON. This page lists each status you can see, where you see it, and what to do.

In the browser

The collector reports errors by throwing or by rejecting the promise from ready() or verify():

Error	Cause	What to do
`octet: invalid apiUrl "…"`	`apiUrl` is not a URL.	Set `apiUrl` to your edge's origin.
`octet: apiUrl must be https://…`	`apiUrl` is not `https://`.	Use `https://`. `http://` works only for `localhost`.
`octet: the collector needs a secure context (https) for crypto.subtle`	The page isn't served over HTTPS, so the browser offers no WebCrypto, which the collector needs to encrypt the collection.	Serve the page over HTTPS. `http://` works only for `localhost`.
`octet: call start() before ready()`	`ready()` ran before `start()`.	Call `start()` at page load.
`octet: unknown mode "…"`	`mode` is not `'full'`, `'lite'` or `'passive'`.	Fix the value, or leave `mode` out to get `full`.
`signal report failed: <status>`	Your edge answered with an error status.	Look up the status under From your edge.
`TypeError` from `fetch`	The browser could not complete the POST. Usually CORS, DNS, TLS, or the edge is down.	Check the browser console, `ALLOWED_ORIGIN`, and the edge's `/health`.
`AbortError`	Your code aborted the collection.	None. No verdict was produced.

Blocked or failed measurements never cause an error. If the WebSocket to your edge fails, the collector sends what it has and results are weaker. The usual causes are a Content Security Policy without wss:// for your edge, and networks that block WebSockets.

From your edge

These are the responses to POST /v1/signals, which the browser sees:

Status	Body	Cause	What to do
`200`	`{"ok":true}`	Octet accepted the session.	None.
`400`	`{"error":"read_failed"}`	The edge could not read the request body.	Retry.
`405`	`{"error":"method_not_allowed"}`	A method other than `POST` or `OPTIONS`.	Use `POST`.
`502`	`{"error":"octet_unreachable"}`	The edge could not reach Octet.	Check `OCTET_URL`, outbound TCP 443, and DNS on the edge host. If you set `OCTET_CA_FILE`, check that Octet's server certificate chains to it. The edge's log has the detail.
Octet's status	`{"error":"octet_rejected","reason":"<reason>","status":<status>}`	Octet refused the session. The edge passes Octet's status and reason code through.	Look up the reason below.

When Octet refuses a session, the edge logs one line with the status and reason, with no end-user data. reason is unknown when Octet's reply carries no plain reason code.

Reasons Octet gives your edge

Status	Reason	Cause	What to do
`401`	`missing_license`	`LICENSE` is not set on the edge.	Set `LICENSE` and restart.
`401`	`bad_vendor_prefix`, `malformed_token`, `bad_footer`, `bad_payload`, `bad_signature`	`LICENSE` is not a valid license token. It may be truncated, or be a read token.	Copy the license token again from Octet's email.
`401`	`wrong_typ`, `wrong_issuer`, `product_not_licensed`, `platform_not_licensed`	The token is valid but not an Octet Browser license.	Use the license token issued for Octet Browser.
`401`	`expired`, `not_yet_valid`, `missing_exp`, `missing_iat_and_nbf`	The license token is outside its validity period, or the edge host's clock is wrong.	Check the host's clock. If it is right, ask Octet for a new license token.
`401`	`revoked`	Octet revoked the license token.	Deploy the replacement Octet sent you, or contact Octet.
`401`	`unknown`, `verify_error`, `license_not_configured`, `license_keys_url_insecure`	Octet could not check the license.	Retry. If it persists, contact developer@octetproof.com.
`401`	`client_cert_required`	The edge presented no client certificate, or one Octet didn't issue.	Check `EDGE_CLIENT_CERT_FILE` and `EDGE_CLIENT_KEY_FILE`, and that the certificate hasn't expired. See Deploy the Edge.
`403`	`client_cert_licence_mismatch`	The client certificate was issued for a different license than the one in `LICENSE`.	Use a certificate issued for this license, from its Edge certificates tab in the Octet portal.
`403`	`client_cert_revoked`	The client certificate was revoked in the Octet portal.	Issue a new certificate in the Edge certificates tab, install it and restart the edge. See Credentials.
`400`	`invalid_json`	The body is not JSON.	Send the collector's POST unchanged.
`400`	`unsealed_bundle`	The body isn't a sealed collection. A collector older than v1.3.0 gets this, and so does an empty `{}` body after a successful license and certificate check.	Update the collector.
`400`	`unknown_seal_key`	The collector is sealed to a key Octet no longer accepts, because the collector is too old.	Update the collector. See Release Notes.
`400`	`bad_seal`, `bad_signature`, `bad_payload`	The sealed collection doesn't open, or its contents don't check out. This usually means a proxy or a script on the page changed the body.	Send the collector's POST unchanged.
`400`	`missing_fields`	The sealed collection opened, but isn't a complete collection.	Send the collector's POST unchanged.
`409`	`replayed_bundle`	Octet accepted this collection recently, through this edge or another. A copy of a collection is refused.	None for the original session, whose verdict stands.
`413`	`payload_too_large`	The body is larger than Octet accepts.	Send the collector's POST unchanged.

A 401 with bad_signature or bad_payload concerns the license token, and a 400 with the same reason concerns the collection.

From the Octet API

These are the responses to GET /v1/verdict/{sessionRef}, which your backend sees:

Status	Body	Cause	What to do
`200`	The verdict	See Verdict Reference.	Apply your policy.
`404`	`{"status":"pending","ref":"…"}`	No verdict for this `sessionRef` yet, the verdict is more than 2 minutes old, the `sessionRef` is wrong, or the session arrived under another license.	Retry with `waitMs`. If it persists, check that the page passes the same `sessionRef` to `start()`.
`401`	`{"error":"unauthorized"}`	No `Authorization: Bearer octet_read_…` header. A license token sent as the bearer also gets this.	Send your read token.
`401`	`{"error":"expired"}`	The read token has expired.	Create a new one. See Credentials.
`401`	`{"error":"revoked"}`	The read token, or its license, has been revoked.	Create a new one, or contact Octet if the license was revoked.
`401`	`{"error":"not_yet_valid"}`	The read token isn't valid yet.	Check your server's clock.
`401`	`malformed_token`, `bad_footer`, `bad_payload`, `bad_signature`, `unknown_kid:…`	The read token is damaged or incomplete.	Copy it again, or create a new one.
`401`	`wrong_typ`, `wrong_issuer`, `wrong_audience`, `missing_scope`, `wrong_env`, `missing_lid`, `missing_exp`, `missing_iat_and_nbf`, `unsupported_schema:…`	The token is not an Octet Browser read token.	Create a read token in the Read tokens tab of your Octet Browser license.
`401`	`read_tokens_not_configured`, `license_keys_url_insecure`, `verify_error`	Octet could not check the read token.	Retry. If it persists, contact developer@octetproof.com.

The 401 reason codes from GET /v1/verdict appear exactly as listed, and some carry a suffix after a colon.

Key set

GET https://geo.octetproof.com/.well-known/browser-verdict-jwks.json returns 200 with the key set. Cache it for up to 5 minutes. See Verify the Signed Token.