Error Handling

NoPII is designed to fail closed: if PII detection or tokenization cannot complete, the request is blocked rather than sent to the LLM provider unprotected. This covers failures of the protection step itself. For what detection scans and what it can miss, see What NoPII scans.

Fail-safe policy

FailureBehavior
Unregistered LLM API key401 - API key not recognized
Account not fully configured503 - Account is not fully configured
Tokenization service returns an error, times out or cannot be reached503 - Request blocked, nothing sent to the LLM
Detokenization service unavailable200 - Response returned with tokens in place (PII was already protected)
A reference code in the reply could not be restored200 with X-NoPII-Unrestored: n - the reply is returned with the code in place and the header counts the codes still in it (0 when every code was restored). See Unrestored reference codes
A reference code could not be restored and the account blocks such replies502 with X-NoPII-Error-Code: unrestored_tokens - the reply is withheld; the body carries the count and the labels of the codes. A stream ends with one nopii.unrestored event before its final event instead
PII detection failure503 - Request blocked, nothing sent to the LLM
Text in an Indian script too long to check413 - One text (a message, system prompt or tool argument) has more than 20,000 characters of Hindi or another Indian script to check. Request blocked; send the text in smaller parts
Request body too large413 - The request body is over 64 MiB (67,108,864 bytes). Request blocked, nothing sent to the LLM. OpenAI callers get code request_too_large, Anthropic callers error type request_too_large.
Lite plan limit reached429 - The Lite plan's 1M protected tokens for the month are used up. The message reads "Lite plan limit reached (1M protected tokens this month). Upgrade to Starter or above to continue." ( upgrade or wait for the monthly reset)
Plan rate limit reached429 - More requests per minute for one key than your plan allows. The message names the plan and its limit (limits by plan). Retry after a short wait, or upgrade for a higher limit.
LLM API errorPass-through - same status code and body from the provider

Key principle: Detection and tokenization failures block the request (503). Detokenization failures pass the response through with tokens visible, and the response says so: NoPII repairs a reference code the model altered slightly (a changed letter case, a dropped leading character, one character inserted, dropped or replaced) when exactly one code of the conversation matches, leaves a code alone whenever the match is not unambiguous, and reports in X-NoPII-Unrestored how many codes are still in the reply. A failure in the protection step never sends unprotected text to the LLM, even at the cost of availability.

Unrestored reference codes

The model sees your data as reference codes and is asked to copy them back verbatim. Most do, and NoPII restores each code to its value before the reply reaches you. A model sometimes alters a code slightly, and NoPII repairs the alteration when exactly one code of the conversation is a plausible original: a letter in another case, a leading underscore or hyphen dropped, or one character inserted, dropped or replaced. A code that two originals could explain, or that matches nothing closely enough, is left as it is: a wrong value would be worse than a visible code.

Every non-streaming reply carries X-NoPII-Unrestored, the number of distinct codes still in the reply across its text and tool arguments, 0 when every code was restored. Streamed replies record the count in the request log instead (the Unrestored column in the admin console). The count never includes the codes themselves or their values.

A code the current session did not create, for example from an earlier session of yours when every request starts a new one, is looked up in your vault and restored too, up to 20 per reply. Codes are the same across all of your sessions, so this only ever reveals your own account's data, and it is never applied to a request made for a named end user. It is on by default; turn off Restore reference codes from earlier sessions (Settings, PII Detection) if every conversation must stay strictly within its own session, and such codes are then left in place and counted.

If a reply with a visible code is worse for you than no reply, turn on Block replies with unrestored reference codes (Settings, PII Detection). A non-streaming reply that still carries a code then comes back as 502 with X-NoPII-Error-Code: unrestored_tokens and a body in your provider's error format carrying count and labels. A streamed reply has already started, so it ends with one extra event: nopii.unrestored carrying the same JSON, right before the stream's final event. The request is billed either way: the provider answered it.

Error response format

Errors that NoPII returns itself follow a standard JSON format:

json
{
  "detail": "Human-readable error message"
}

A request blocked because PII detection or tokenization could not complete always returns 503 with this body, whatever the cause:

json
{
  "detail": "PII tokenization service unavailable. Request blocked to prevent data leakage."
}

Status codes

CodeMeaning
400Bad request - validation error in request body
401Invalid or missing authentication (unregistered API key)
403The feature is not included in your plan; the message names the plans that include it
404Resource not found
413The request body is over 64 MiB, or a text has too much Hindi or other Indian-script content to check in one request (limit 20,000 characters per text)
429Lite plan limit reached (upgrade to Starter or above, or wait for the monthly reset)
502The reply still carried a reference code and the account blocks such replies (X-NoPII-Error-Code: unrestored_tokens)
503Service unavailable - PII detection or tokenization could not complete, or account not fully configured (request blocked, fail-safe)

Handling errors in your application

Since NoPII passes through LLM provider errors unchanged, your existing error handling code works as-is. The only new error to handle is 503, which NoPII returns when it blocks a request because PII detection or tokenization could not complete. It is safe to retry:

python
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.nopii.co")

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}]
    )
except APIStatusError as e:
    if e.status_code == 503:
        # NoPII blocked the request because PII protection could not complete
        # Retry later or fall back to a non-PII workflow
        print("PII protection unavailable, retry later")
    else:
        # Standard LLM API error (rate limit, invalid model, etc.)
        raise

Related