Error Handling

NoPII is designed with a fail-safe principle: it will never forward unsanitized PII to an LLM provider. If something goes wrong during tokenization, the request is blocked rather than sent unprotected.

Fail-safe policy

FailureBehavior
Unregistered LLM API key401 - API key not recognized
Account not fully configured503 - Account is not fully configured
Tokenization service unavailable503 - Request blocked to prevent PII leakage
Detokenization service unavailable200 - Response returned with tokens in place (PII was already protected)
PII detection failure503 - Request blocked to prevent PII leakage
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
Free tier limit exceeded429 - Monthly token quota exhausted ( upgrade to paid or wait for monthly reset)
LLM API errorPass-through - same status code and body from the provider

Key principle: Tokenization failures block the request (503). Detokenization failures pass the response through with tokens visible. This ensures PII never reaches the LLM, even at the cost of availability.

Error response format

All errors follow a standard JSON format:

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

Status codes

CodeMeaning
400Bad request - validation error in request body
401Invalid or missing authentication (unregistered API key)
404Resource not found
413A text has too much Hindi or other Indian-script content to check in one request (limit 20,000 characters per text)
429Free tier token limit exceeded (upgrade to paid or wait for monthly reset)
503Service unavailable - PII protection failure (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 indicates NoPII blocked the request to protect PII:

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 - PII protection service unavailable
        # Retry later or fall back to a non-PII workflow
        print("PII protection service unavailable")
    else:
        # Standard LLM API error (rate limit, invalid model, etc.)
        raise

Related