Error Handling

HTTP Status Codes

The Prompt Inspector API uses standard HTTP status codes to indicate the outcome of a request.

Status Code	Meaning	Description
`200`	OK	Request succeeded. Detection result is in the response body.
`401`	Unauthorized	Missing or invalid API key. Check your `X-App-Key` header.
`403`	Forbidden	API key is valid but lacks permission for this operation.
`413`	Payload Too Large	Input text exceeds the maximum length for your plan.
`422`	Unprocessable Entity	Invalid request body (e.g., missing `input_text` field).
`429`	Too Many Requests	Rate limit or monthly quota exceeded.
`500`	Internal Server Error	Unexpected server error. Please try again or contact support.
`502`	Bad Gateway	Upstream service unreachable. Retry after a short delay.
`503`	Service Unavailable	Server is temporarily unavailable. Retry with exponential backoff.

Error Response Format

All error responses follow this structure:

{
  "detail": "A human-readable description of the error."
}

SDK Exceptions

Both SDKs provide a typed exception hierarchy so you can handle errors precisely.

Exception Hierarchy

PromptInspectorError (base)
├── AuthenticationError    — Invalid or missing API key
├── ValidationError        — Invalid input (empty text, text too long)
├── APIError               — Server returned an error (4xx/5xx)
├── TimeoutError           — Request exceeded timeout
└── ConnectionError        — Cannot connect to the API server

Python

from prompt_inspector import (
    PromptInspector,
    PromptInspectorError,
    AuthenticationError,
    ValidationError,
    APIError,
    TimeoutError,
    ConnectionError,
)

try:
    client = PromptInspector(api_key="your-api-key")
    result = client.detect("test input")
    print(f"Safe: {result.is_safe}")
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except ValidationError as e:
    print(f"Invalid input: {e}")
except TimeoutError as e:
    print(f"Timed out: {e}")
except ConnectionError as e:
    print(f"Connection failed: {e}")
except APIError as e:
    print(f"API error (HTTP {e.status_code}): {e}")
except PromptInspectorError as e:
    print(f"SDK error: {e}")

Node.js / TypeScript

import {
  PromptInspector,
  PromptInspectorError,
  AuthenticationError,
  ValidationError,
  APIError,
  TimeoutError,
  ConnectionError,
} from "prompt-inspector";

try {
  const client = new PromptInspector({ apiKey: "your-api-key" });
  const result = await client.detect("test input");
  console.log(`Safe: ${result.isSafe}`);
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error(`Auth failed: ${err.message}`);
  } else if (err instanceof ValidationError) {
    console.error(`Invalid input: ${err.message}`);
  } else if (err instanceof TimeoutError) {
    console.error(`Timed out: ${err.message}`);
  } else if (err instanceof ConnectionError) {
    console.error(`Connection failed: ${err.message}`);
  } else if (err instanceof APIError) {
    console.error(`API error (HTTP ${err.statusCode}): ${err.message}`);
  } else if (err instanceof PromptInspectorError) {
    console.error(`SDK error: ${err.message}`);
  }
}

Common Errors & Solutions

401 Unauthorized — Missing or invalid API key

Cause: The X-App-Key header is missing or the key is incorrect/inactive.Solution:

Verify your API key is correct and active in the Dashboard.
Ensure the key is passed via X-App-Key header or Authorization: Bearer <key>.
If using an SDK, check that api_key / apiKey is set or the PMTINSP_API_KEY environment variable is defined.

413 Payload Too Large — Text exceeds maximum length

Cause: The input_text exceeds the maximum character limit for your subscription plan.Solution:

Truncate or split your input text before sending.
Upgrade your plan at promptinspector.io for higher limits.

422 Unprocessable Entity — Invalid request body

Cause: The request body is malformed or missing the required input_text field.Solution:

Ensure the request body is valid JSON with Content-Type: application/json.
Include the input_text field with a non-empty string value.

429 Too Many Requests — Rate limit exceeded

Cause: You have exceeded the per-minute rate limit or monthly request quota for your plan.Solution:

Implement exponential backoff and retry logic.
Check your current usage in the Dashboard.
Upgrade your plan for higher rate limits and quotas.

Connection / Timeout errors

Cause: Network issues or the API server is temporarily unreachable.Solution:

Check your network connectivity.
Increase the timeout setting in your SDK client.
Implement retry logic with exponential backoff.
Verify the base_url / baseUrl is correct (default: https://promptinspector.io).

Retry Strategy

For production applications, we recommend implementing a retry strategy with exponential backoff:

import time
from prompt_inspector import PromptInspector, APIError, TimeoutError, ConnectionError

client = PromptInspector(api_key="your-api-key")

def detect_with_retry(text, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.detect(text)
        except (TimeoutError, ConnectionError):
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # 1s, 2s, 4s
        except APIError as e:
            if e.status_code == 429:
                time.sleep(2 ** attempt)
                continue
            raise

For persistent issues, contact us at [email protected] or open an issue on GitHub.

Getting Started

Essentials

HTTP Status Codes

Error Response Format

SDK Exceptions

Exception Hierarchy

Python

Node.js / TypeScript

Common Errors & Solutions

Retry Strategy

​HTTP Status Codes

​Error Response Format

​SDK Exceptions

​Exception Hierarchy

​Python

​Node.js / TypeScript

​Common Errors & Solutions

​Retry Strategy

HTTP Status Codes

Error Response Format

SDK Exceptions

Exception Hierarchy

Python

Node.js / TypeScript

Common Errors & Solutions

Retry Strategy