Skip to Content
Troubleshooting

Troubleshooting

Common issues and solutions when working with Expunct.

Authentication errors

401 Unauthorized

The API key is missing or invalid.

  • Verify your API key starts with pk_live_ (production) or pk_test_ (testing)
  • Check that the key is passed in the X-API-Key header (or via the SDK constructor)
  • Confirm the key has not been revoked in the dashboard 
# Verify your key works
curl -s -o /dev/null -w "%{http_code}" \
  -H "X-API-Key: pk_live_..." \
  https://api.pii-redactor.dev/api/v1/health
# Expected: 200

403 Forbidden

The API key does not have permission for the requested resource. This can happen when:

  • Using a test key (pk_test_) against production resources
  • The key’s tenant does not own the requested policy or job

Rate limiting

429 Too Many Requests

You have exceeded the rate limit for your plan.

  • The response includes a Retry-After header with the number of seconds to wait
  • Both SDKs automatically retry with exponential backoff (up to 3 retries)
  • If you consistently hit limits, contact support to discuss plan upgrades
# The SDK handles 429 automatically, but you can configure retries:
from pii_redactor_sdk import PiiRedactor
 
client = PiiRedactor(
    api_key="pk_live_...",
    max_retries=5,  # default is 3
)

Not found errors

404 Not Found

The requested resource does not exist.

  • Job not found: Verify the job_id is correct. Jobs are cleaned up after the configured retention period (default: 30 days).
  • Policy not found: Verify the policy_id is correct and belongs to your tenant.
  • Endpoint not found: Check that you are using the correct API version (/api/v1/).

Validation errors

422 Unprocessable Entity

The request body failed validation. Common causes:

ErrorCauseSolution
text field is requiredEmpty or missing text fieldProvide non-empty text
invalid URI schemeURI does not start with s3://, gs://, or https://Use a supported URI scheme
too many URIsBatch request exceeds 100 URIsSplit into multiple batches of 100 or fewer
unknown entity typeUnrecognized value in entities listCheck the Entity Types page for valid values
invalid languageUnsupported language codeUse en or es

Connection errors

If you cannot connect to the API at all:

  1. Verify the base URL — The default is https://api.pii-redactor.dev. If you are running a self-hosted deployment, confirm the URL with your infrastructure team.
  2. Check network connectivity — Ensure your machine can reach the API endpoint. Try curl https://api.pii-redactor.dev/api/v1/health.
  3. Check firewall rules — The API runs on HTTPS (port 443). Ensure outbound traffic is allowed.
  4. Verify the service is running — For self-hosted deployments, check that all containers are healthy: kubectl get pods -n pii-redactor.

Job status reference

When processing files or batches, jobs go through the following statuses:

StatusDescription
queuedJob has been accepted and is waiting to be processed
processingJob is currently being processed
completedJob finished successfully. Output is available.
failedJob failed due to a processing error (e.g., corrupt file, unsupported format)
errorJob failed due to a system error. May be retried.

Retry patterns

Automatic retries (SDK)

Both SDKs automatically retry failed requests for transient errors:

  • Retried: 5xx server errors, 429 rate limits, network timeouts
  • Not retried: 4xx client errors (except 429)
  • Default: Up to 3 retries with exponential backoff
  • Backoff: 1s, 2s, 4s (doubling each retry)

Manual retry for failed jobs

If a job fails, you can resubmit it:

status = client.jobs.get(job_id)
if status.status in ("failed", "error"):
    # Resubmit the same file
    new_job = client.redact.file(file_path="/path/to/document.pdf")
    print(f"Resubmitted as: {new_job.job_id}")

Polling retry

When polling for job status, use reasonable intervals to avoid unnecessary load:

import time
 
poll_interval = 2  # seconds
max_wait = 300     # 5 minutes
 
elapsed = 0
while elapsed < max_wait:
    status = client.jobs.get(job_id)
    if status.status in ("completed", "failed", "error"):
        break
    time.sleep(poll_interval)
    elapsed += poll_interval
else:
    print("Timed out waiting for job to complete")

MCP Server troubleshooting

The Expunct MCP Server connects Claude Code (and other MCP clients) to the Expunct API.

Common issues

Server fails to start

  • Ensure Node.js >= 18 is installed: node --version
  • Verify the PII_REDACTOR_API_KEY environment variable is set
  • Verify the PII_REDACTOR_BASE_URL environment variable is set (if using a custom deployment)

Tools not appearing in Claude Code

  • Check that the MCP server is configured in your Claude Code settings (~/.claude/settings.json or project-level .claude/settings.json)
  • Run the server manually to check for errors: 
    PII_REDACTOR_API_KEY=pk_live_... npx @pii-redactor/mcp

Authentication errors from MCP tools

  • The MCP server uses the PII_REDACTOR_API_KEY environment variable. Ensure it contains a valid key.
  • Test the key directly: 
    curl -H "X-API-Key: $PII_REDACTOR_API_KEY" \
  https://api.pii-redactor.dev/api/v1/health

Getting help

If your issue is not covered here:

WorkflowsOverview