Skip to content

Error Handling

All errors inherit from PrimitifError, so you can catch broadly or narrowly.

from primitif import PrimitifError, AuthError, NetworkError
from primitif.mail import MailRateLimitError

try:
    mb.send("user@test.com", "Hi", "Hello")
except MailRateLimitError as e:
    print(f"Slow down — retry after {e.retry_after}s")
except NetworkError:
    print("Network issue — timeout or DNS failure")
except AuthError:
    print("Bad credentials")
except PrimitifError:
    print("Something went wrong")

Hierarchy

PrimitifError
├── AuthError          # 401 — invalid API key or token
├── NotFoundError      # 404 — resource doesn't exist
├── ConflictError      # 409 — duplicate resource
├── ValidationError    # 422 — invalid input
├── RateLimitError     # 429 — too many requests
├── ServerError        # 5xx — server error
├── NetworkError       # connection failure
└── InvalidSignature   # webhook signature mismatch

Product-specific exceptions (e.g. MailAuthError, ApprovalNotFoundError) inherit from both the product base and the generic error, so you can catch at either level.

Reference

PrimitifError 

PrimitifError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: Exception

Base exception for all Primitif SDK errors.

AuthError 

AuthError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

401 — invalid or missing credentials.

NotFoundError 

NotFoundError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

404 — resource not found.

ConflictError 

ConflictError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

409 — resource conflict.

ValidationError 

ValidationError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

422 — invalid request payload.

RateLimitError 

RateLimitError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

429 — rate limit exceeded.

retry_after property 

retry_after: float | None

Seconds to wait before retrying, from the Retry-After header.

ServerError 

ServerError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

5xx — server error.

NetworkError 

NetworkError(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

Network-level failure — timeout, DNS, TCP, or TLS error.

InvalidSignature 

InvalidSignature(
    message: str = "",
    *,
    status_code: int = 0,
    code: str = "",
    response: "httpx.Response | None" = None,
    request_id: str | None = None,
)

Bases: PrimitifError

Webhook signature verification failed.