Sign in Contact

Errors

Handle failures explicitly.

smtpRS returns standard HTTP status codes with JSON details. Treat authentication, entitlement, quota, validation, and temporary service failures differently.

Status codes.

Status Common detail Recommended handling
400 Malformed request or invalid option. Fix the request before retrying.
401 missing api key or invalid api key Check whether the key is present, copied correctly, and active.
403 inactive api key, tenant is not active, or feature_not_available Check workspace status, entitlement, and plan.
422 Validation error. Ensure the body contains a valid email string.
429 monthly_credit_limit_exceeded or too many requests. Back off, reduce request rate, or upgrade/add credits.
503 Quota lookup, key lookup, or usage record temporarily unavailable. Retry with exponential backoff and alert if repeated.

Error examples.

Missing key
{
  "detail": "missing api key"
}
Feature unavailable
{
  "detail": {
    "error": "feature_not_available",
    "feature": "feature_strict_score",
    "tier": "BASIC",
    "message": "This scoring mode is not available on the current tier."
  }
}
Monthly credit limit exceeded
{
  "detail": {
    "error": "monthly_credit_limit_exceeded",
    "message": "Monthly credit limit exceeded for the current tier.",
    "limit": 10000,
    "used": 9999,
    "credit_cost": 3,
    "projected_used": 10002
  }
}

Retry guidance.

  • Do not retry 401, 403, or 422
  • Retry true rate-limit 429 responses only after waiting.
  • Retry transient 5xx responses with exponential backoff and an idempotency key.
  • Do not log raw API keys in application logs or error traces.

The Python SDK does not retry by default. Set max_network_retries on ParavaneClient to retry network failures, 429, and 5xx responses. Supply an idempotency_key for requests your application may repeat after a timeout.

Structured Python errors
from paravane import (
    AuthenticationError,
    ParavaneClient,
    PermissionDeniedError,
    QuotaExceededError,
    RateLimitError,
    ValidationError,
)

client = ParavaneClient(max_network_retries=2)

try:
    result = client.smtprs.analyze(
        "alice@example.com",
        idempotency_key="signup-check-123",
    )
except AuthenticationError:
    print("Check the API key.")
except PermissionDeniedError:
    print("Check the workspace plan and entitlement.")
except QuotaExceededError:
    print("The workspace has exhausted its credits.")
except RateLimitError:
    print("Wait before retrying.")
except ValidationError as exc:
    print(exc.status_code, exc.code, exc.request_id)