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
| Failure | Behavior |
|---|---|
| Unregistered LLM API key | 401 - API key not recognized |
| Account not fully configured | 503 - Account is not fully configured |
| Tokenization service returns an error, times out or cannot be reached | 503 - Request blocked, nothing sent to the LLM |
| Detokenization service unavailable | 200 - Response returned with tokens in place (PII was already protected) |
| A reference code in the reply could not be restored | 200 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 replies | 502 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 failure | 503 - Request blocked, nothing sent to the LLM |
| Text in an Indian script too long to check | 413 - 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 large | 413 - 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 reached | 429 - 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 reached | 429 - 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 error | Pass-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:
{
"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:
{
"detail": "PII tokenization service unavailable. Request blocked to prevent data leakage."
}Status codes
| Code | Meaning |
|---|---|
| 400 | Bad request - validation error in request body |
| 401 | Invalid or missing authentication (unregistered API key) |
| 403 | The feature is not included in your plan; the message names the plans that include it |
| 404 | Resource not found |
| 413 | The 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) |
| 429 | Lite plan limit reached (upgrade to Starter or above, or wait for the monthly reset) |
| 502 | The reply still carried a reference code and the account blocks such replies (X-NoPII-Error-Code: unrestored_tokens) |
| 503 | Service 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:
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.)
raiseRelated
- API Reference - Full endpoint documentation
- How It Works - Understand the tokenization flow