Errors and limits
Every Sentisec-specific error you can get back, what caused it, and the exact fix — plus how request-rate limits are surfaced.
Sentisec returns the upstream provider's own errors unchanged. The codes below are the ones Sentisec itself raises — each one names a different operator action, which is why they are not collapsed into a single "something is wrong" response.
Sentisec errors carry a JSON body with a stable error string:
{ "error": "provider_unavailable", "hint": "…" }Connecting to an upstream
| Status | error | Cause | Fix |
|---|---|---|---|
503 | provider_unavailable | The provider you selected is not connected on this deployment at all. | Pick a provider from Providers, or ask us about the one you need. No amount of workspace configuration fixes this. |
401 / 402 | no_upstream_credential | The provider is available, but this workspace has no key stored for it. OpenAI-shaped endpoints return 401; the Anthropic Messages endpoint returns 402. | Add the provider key in the dashboard under Settings → Providers, in Provider keys, then retry. No restart needed. The failed request's row under Requests shows No provider key with an Add … key action that opens that page with the provider selected. |
400 | upstream_provider_header_invalid | X-Sentisec-Upstream-Provider carried a name Sentisec does not recognise. | Check the spelling against Providers, or drop the header and let the model id select. |
404 | embeddings_not_supported_for_provider | The selected vendor has no OpenAI-shape embeddings endpoint. | Switch to a provider that does — see Embeddings. |
The 503 / 401 split is the one worth internalising: 503 means
nothing you can configure, 401 means paste a key. Treating them as
one error sends an operator hunting for a missing key that was never the
problem.
Authentication
| Status | Cause | Fix |
|---|---|---|
401 | Missing, malformed, revoked, or wrong-surface credential. | Chat endpoints take a workspace key (sk_sentisec_…); administration endpoints take an admin session token. Sending one where the other belongs returns 401. |
403 | Either your role is insufficient for the action, or you hold no membership in that workspace at all. | Admin-only actions are listed in Roles and permissions. |
404 | The workspace or session does not exist, or has been deleted. | Looking a workspace up by id also returns 404 when it belongs to another organisation, and a session id from another workspace returns 404 rather than 403 — a probe cannot confirm a foreign id is real. |
Repeated failed authentication from one address is backed off: after 10
401s within a minute, further attempts from that address return 429
with X-Sentisec-Limit: auth_backoff and Retry-After: 60 until it
cools down. This applies to credential guessing, not to a
correctly-keyed client.
Request bodies
A malformed body returns 422 with the offending field named. The two
that trip people up most:
- Upstream-credential rotation takes an encrypted credential. A body that sends a plaintext field instead is rejected.
- Connection testing takes
provider_id, notprovider.
Rate limits
Each plan allows a number of requests and tokens per minute. A request
over either limit is refused with 429 before it reaches your provider:
| Part | Meaning |
|---|---|
Retry-After | Seconds until the minute window resets. |
X-Sentisec-Limit | request_limit_exceeded or token_budget_exceeded. |
| Body | Your provider's own rate-limit error, so your SDK reads it as a rate limit and retries. |
A 503 with X-Sentisec-Limit: limits_unavailable means the limits
could not be checked at that moment; retry shortly. The limits per
plan, how a request is counted, and where to read how often a workspace
was refused are in Rate limits.
The free plan additionally carries a monthly session allowance; paid plans are unlimited on sessions. Need a higher ceiling? Get in touch.
When Sentisec itself is degraded
The design goal is that a Sentisec problem never becomes your outage:
- If recording falls behind, requests are still served and inspected;
the response carries
X-Sentisec-Telemetry: degraded. - If the alerting or export path fails, it is logged and your traffic continues — the recorded evidence, not the notification, is the system of record.
- Protection itself fails the other way. If Sentisec cannot determine what a workspace's policy is, it resolves to enforce, not to open. A workspace is never accidentally unprotected.
Related
The streaming verdict frame
Streamed responses end with one extra SSE comment carrying the turn's verdict — its exact shape, what to do with it, and why it cannot break a client that ignores it.
Rate limits
Each plan's per-minute request and token limits, how a request is counted against them, what a refused request looks like, and where to see how often it happens.