feat(errors): actionable messages + PlanNotEntitledError for plan-gated 403s

[abhishekmishragithub]

DevX pass (backward-compatible) — error ergonomics

First slice of the DevX pass. All additive; nothing renamed or removed. Detection is now spec-backed against the atoms main-backend middleware, not a guess.

PlanNotEntitledError (plan / entitlement gating)

The platform (main-backend access.middleware.ts) rejects a plan-gated feature with HTTP 400, body {status: false, errors: ["Your plan has no access to <feature>, please upgrade to a higher plan…"]} (and "reached the maximum … for your plan" limit variants). Such a 400 is now raised as PlanNotEntitledError — a subclass of BadRequestError via BadRequestError.__new__:

from smallestai import PlanNotEntitledError
try:
    client.atoms.campaigns.create(...)   # a plan-gated feature
except PlanNotEntitledError:
    ...  # "needs a higher plan"

except BadRequestError still catches it (subclass) — fully backward-compatible. Gated features per the platform map: campaigns, knowledge base, webhooks, integrations, phone numbers, inbound/outbound telephony, chat, waves models, gpt-4o, electron, voice-clone.

Note: this is HTTP 400, not 403. HTTP 403 is a separate org allow-list gate ("… not available for your organization", e.g. GPT 5.2) that the user cannot self-upgrade — that gets its own hint, no special type.

Actionable error messages

ApiError.__str__ appends a one-line hint:

• 401 → check SMALLEST_API_KEY + where to get a key.
• 400 (plan-gated) → upgrade your plan.
• 403 (org-gated) → contact your account team.

Public errors module

New smallestai.errors re-exporting the common types; PlanNotEntitledError on the package root.

Notes

• Hand-maintained files (core/api_error.py, core/_error_hints.py, atoms/errors/bad_request_error.py, errors.py) added to .fernignore with re-sync comments.
• No version bump — accumulating the DevX pass (with feat(waves): TTS helpers + x-expire-content (DevX, cuts 5.5.0) #88); cut one 5.5.0 when the pass lands.
• 8 unit tests using the real platform envelope; mypy-clean.

🤖 Generated with Claude Code