Version 0.5.0: the spec at API 1.18.0, validation error models removed

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.5.0 (2026-11-12)
+
+Follows API 1.18.0. The saved spec has 145 operations and the models are regenerated from it.
+No client method, argument or return type changed. An API key is sent as before.
+
+Breaking: the models `HTTPValidationError` and `ValidationError` are removed from `faxforagents.models`.
+The server never sent that shape. A 422 is the error envelope and the client raises `InvalidRequestError`, as it did in 0.4.1.
+Code that imported either model has to delete the import. Nothing replaces them. pydantic's own `ValidationError` is not affected.
+
+Breaking: `ErrorEnvelope.error` is the new model `ErrorBody`, where 0.4.1 declared a plain dict. Read `env.error.code`, not `env.error["code"]`.
+`ErrorBody` has `code`, `message`, `retryable`, `correlation_id` and `details`. `correlation_id` may be `None`.
+Raised errors are the same classes with the same attributes.
+
+`one_time_sends.create` can raise `RateLimitedError` with `details["cap"]` equal to `upload_queue`. Too many files are being read at once, so wait `retry_after` seconds.
+Other model names, fields and optionality are kept.
+
 ## 0.4.1 (2026-11-12)
 
 Follows API 1.17.0. The saved spec has 145 operations and the models are regenerated from it.

README.md

@@ -152,6 +152,10 @@ except APIError as exc:
 `ServerError` (5xx) are all `APIError`. `APIConnectionError` and `APITimeoutError` mean the API was
 not reached.
 
+Every refusal is the same envelope, a 422 for a field that fails validation included. A 413
+`payload_too_large` is a plain `APIError`: the body is over the limit of its route. The published
+limits are in one table at <https://faxforagents.com/docs/limits/>.
+
 ## Approvals
 
 A live send needs either a human approval bound to the quote or a delegated policy that allows it.
@@ -295,7 +299,7 @@ ruff check src tests && mypy src
 sh scripts/truthcheck.sh
 ```
 
-`spec/openapi.yaml` follows the public document at API version 1.17.0 and keeps the schemas of the earlier live documents.
+`spec/openapi.yaml` follows the public document at API version 1.18.0 and keeps the schemas of the earlier live documents.
 It also retains earlier public model names and route-documented response additions.
 To refresh it, merge the live schemas while preserving existing declarations, then run `uv run python scripts/gen_models.py`.
 Keep new response fields optional so older payloads and existing callers remain valid.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "faxforagents"
-version = "0.4.1"
+version = "0.5.0"
 description = "Python client for Fax for Agents: a fax API, a hosted MCP server and SDKs built so AI agents can send and receive faxes."
 readme = "README.md"
 requires-python = ">=3.10"