workly 0.1.0__py3-none-any.whl

workly/_requests.py

@@ -0,0 +1,322 @@
+"""Request building shared by the sync and async clients.
+
+Each API operation is a function returning a `Request`; the clients only
+send it and decode the response, so the two stay in step.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Required, TypedDict
+from urllib.parse import quote
+
+from ._models import AlertChannelType, HTTPMethod, RunState, TaskState
+
+DEFAULT_URL = "http://localhost:7337"
+
+try:
+    __version__ = version("workly")
+except PackageNotFoundError:  # running from a source tree
+    __version__ = "0.0.0"
+
+
+@dataclass(frozen=True, slots=True)
+class Request:
+    method: str
+    path: str
+    params: dict[str, str] = field(default_factory=dict[str, str])
+    json: Any = None
+    headers: dict[str, str] = field(default_factory=dict[str, str])
+    idempotent: bool = False
+    """Safe to resend even if the server may have processed it."""
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    base_url: str
+    headers: dict[str, str]
+
+
+def client_config(url: str | None, api_key: str | None) -> ClientConfig:
+    base_url = (url or os.environ.get("WORKLY_URL") or DEFAULT_URL).rstrip("/")
+    api_key = api_key if api_key is not None else os.environ.get("WORKLY_API_KEY")
+    headers = {"User-Agent": f"workly-python/{__version__}", "Accept": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return ClientConfig(base_url, headers)
+
+
+class TaskSpec(TypedDict, total=False):
+    """One task for `tasks.enqueue_many`. Same fields as `tasks.enqueue`."""
+
+    url: Required[str]
+    payload: Any
+    body: str
+    content_type: str
+    method: HTTPMethod
+    headers: Mapping[str, str]
+    delay_seconds: float
+    run_at: datetime
+    idempotency_key: str
+    max_attempts: int
+    timeout_seconds: float
+
+
+def task_body(spec: Mapping[str, Any]) -> dict[str, Any]:
+    body: dict[str, Any] = {}
+    for key, value in spec.items():
+        if value is None:
+            continue
+        if key == "run_at":
+            value = _timestamp(value, "run_at")
+        elif key == "headers":
+            value = dict(value)
+        body[key] = value
+    if "payload" in body and "body" in body:
+        raise ValueError("pass payload or body, not both")
+    if "delay_seconds" in body and "run_at" in body:
+        raise ValueError("pass delay_seconds or run_at, not both")
+    return body
+
+
+def _timestamp(value: datetime, name: str) -> str:
+    if value.tzinfo is None:
+        raise ValueError(f"{name} must be timezone-aware, e.g. datetime.now(timezone.utc)")
+    return value.isoformat()
+
+
+def _q(segment: str) -> str:
+    return quote(segment, safe="")
+
+
+def _traceparent(traceparent: str | None) -> dict[str, str]:
+    return {"traceparent": traceparent} if traceparent else {}
+
+
+# Queues
+
+
+def list_queues() -> Request:
+    return Request("GET", "/v1/queues", idempotent=True)
+
+
+def get_queue(name: str) -> Request:
+    return Request("GET", f"/v1/queues/{_q(name)}", idempotent=True)
+
+
+def put_queue(name: str, config: dict[str, Any]) -> Request:
+    body = {k: v for k, v in config.items() if v is not None}
+    return Request("PUT", f"/v1/queues/{_q(name)}", json=body, idempotent=True)
+
+
+def delete_queue(name: str) -> Request:
+    return Request("DELETE", f"/v1/queues/{_q(name)}", idempotent=True)
+
+
+def pause_queue(name: str) -> Request:
+    return Request("POST", f"/v1/queues/{_q(name)}/pause", idempotent=True)
+
+
+def resume_queue(name: str) -> Request:
+    return Request("POST", f"/v1/queues/{_q(name)}/resume", idempotent=True)
+
+
+def cancel_pending_tasks(name: str) -> Request:
+    return Request("POST", f"/v1/queues/{_q(name)}/cancel-pending", idempotent=True)
+
+
+def retry_failed_tasks(name: str, last_error: str | None) -> Request:
+    params = {} if last_error is None else {"last_error": last_error}
+    return Request("POST", f"/v1/queues/{_q(name)}/retry-failed", params=params, idempotent=True)
+
+
+def get_queue_failures(name: str, limit: int | None) -> Request:
+    params = {} if limit is None else {"limit": str(limit)}
+    return Request("GET", f"/v1/queues/{_q(name)}/failures", params=params, idempotent=True)
+
+
+def get_queue_activity(name: str, since: datetime | None) -> Request:
+    params = {} if since is None else {"since": _timestamp(since, "since")}
+    return Request("GET", f"/v1/queues/{_q(name)}/activity", params=params, idempotent=True)
+
+
+def get_activity(range: str | None) -> Request:
+    params = {} if range is None else {"range": range}
+    return Request("GET", "/v1/activity", params=params, idempotent=True)
+
+
+# Tasks
+
+
+def enqueue(queue: str, spec: Mapping[str, Any], traceparent: str | None) -> Request:
+    body = task_body(spec)
+    return Request(
+        "POST",
+        f"/v1/queues/{_q(queue)}/tasks",
+        json=body,
+        headers=_traceparent(traceparent),
+        idempotent="idempotency_key" in body,
+    )
+
+
+def enqueue_many(queue: str, specs: list[Mapping[str, Any]], traceparent: str | None) -> Request:
+    tasks = [task_body(s) for s in specs]
+    return Request(
+        "POST",
+        f"/v1/queues/{_q(queue)}/tasks:batch",
+        json={"tasks": tasks},
+        headers=_traceparent(traceparent),
+        idempotent=all("idempotency_key" in t for t in tasks),
+    )
+
+
+def search_tasks(
+    *,
+    queue: str | None,
+    state: TaskState | None,
+    idempotency_key: str | None,
+    last_error: str | None,
+    created_after: datetime | None,
+    created_before: datetime | None,
+    cursor: str | None,
+    limit: int | None,
+) -> Request:
+    params: dict[str, str] = {}
+    if queue is not None:
+        params["queue"] = queue
+    if state is not None:
+        params["state"] = state
+    if idempotency_key is not None:
+        params["idempotency_key"] = idempotency_key
+    if last_error is not None:
+        params["last_error"] = last_error
+    if created_after is not None:
+        params["created_after"] = _timestamp(created_after, "created_after")
+    if created_before is not None:
+        params["created_before"] = _timestamp(created_before, "created_before")
+    if cursor is not None:
+        params["cursor"] = cursor
+    if limit is not None:
+        params["limit"] = str(limit)
+    return Request("GET", "/v1/tasks", params=params, idempotent=True)
+
+
+def get_task(task_id: str) -> Request:
+    return Request("GET", f"/v1/tasks/{_q(task_id)}", idempotent=True)
+
+
+def list_attempts(task_id: str) -> Request:
+    return Request("GET", f"/v1/tasks/{_q(task_id)}/attempts", idempotent=True)
+
+
+def get_task_delivery(task_id: str) -> Request:
+    return Request("GET", f"/v1/tasks/{_q(task_id)}/delivery", idempotent=True)
+
+
+def cancel_task(task_id: str) -> Request:
+    return Request("POST", f"/v1/tasks/{_q(task_id)}/cancel", idempotent=True)
+
+
+def retry_task(task_id: str) -> Request:
+    # Not idempotent: resending could replay a task that already finished again.
+    return Request("POST", f"/v1/tasks/{_q(task_id)}/retry")
+
+
+# Schedules and runs
+
+
+def list_schedules() -> Request:
+    return Request("GET", "/v1/schedules", idempotent=True)
+
+
+def get_schedule(name: str) -> Request:
+    return Request("GET", f"/v1/schedules/{_q(name)}", idempotent=True)
+
+
+def put_schedule(name: str, config: Mapping[str, Any]) -> Request:
+    body: dict[str, Any] = {}
+    for key, value in config.items():
+        if value is None:
+            continue
+        body[key] = dict(value) if key == "headers" else value
+    if "payload" in body and "body" in body:
+        raise ValueError("pass payload or body, not both")
+    return Request("PUT", f"/v1/schedules/{_q(name)}", json=body, idempotent=True)
+
+
+def delete_schedule(name: str) -> Request:
+    return Request("DELETE", f"/v1/schedules/{_q(name)}", idempotent=True)
+
+
+def pause_schedule(name: str) -> Request:
+    return Request("POST", f"/v1/schedules/{_q(name)}/pause", idempotent=True)
+
+
+def resume_schedule(name: str) -> Request:
+    return Request("POST", f"/v1/schedules/{_q(name)}/resume", idempotent=True)
+
+
+def preview_cron(cron: str, timezone: str | None) -> Request:
+    params = {"cron": cron} if timezone is None else {"cron": cron, "timezone": timezone}
+    return Request("GET", "/v1/cron/preview", params=params, idempotent=True)
+
+
+def trigger_schedule(name: str) -> Request:
+    # Not idempotent: resending would create a second run.
+    return Request("POST", f"/v1/schedules/{_q(name)}/trigger")
+
+
+def list_runs(
+    name: str, *, state: RunState | None, cursor: str | None, limit: int | None
+) -> Request:
+    params: dict[str, str] = {}
+    if state is not None:
+        params["state"] = state
+    if cursor is not None:
+        params["cursor"] = cursor
+    if limit is not None:
+        params["limit"] = str(limit)
+    return Request("GET", f"/v1/schedules/{_q(name)}/runs", params=params, idempotent=True)
+
+
+def get_run(run_id: str) -> Request:
+    return Request("GET", f"/v1/runs/{_q(run_id)}", idempotent=True)
+
+
+def list_run_attempts(run_id: str) -> Request:
+    return Request("GET", f"/v1/runs/{_q(run_id)}/attempts", idempotent=True)
+
+
+def get_run_delivery(run_id: str) -> Request:
+    return Request("GET", f"/v1/runs/{_q(run_id)}/delivery", idempotent=True)
+
+
+def cancel_run(run_id: str) -> Request:
+    return Request("POST", f"/v1/runs/{_q(run_id)}/cancel", idempotent=True)
+
+
+def retry_run(run_id: str) -> Request:
+    # Not idempotent, like retry_task.
+    return Request("POST", f"/v1/runs/{_q(run_id)}/retry")
+
+
+def list_alert_channels() -> Request:
+    return Request("GET", "/v1/alert-channels", idempotent=True)
+
+
+def create_alert_channel(type: AlertChannelType, target: str) -> Request:
+    # Not idempotent: a resend after it was added gets alert_channel_exists.
+    return Request("POST", "/v1/alert-channels", json={"type": type, "target": target})
+
+
+def delete_alert_channel(channel_id: str) -> Request:
+    return Request("DELETE", f"/v1/alert-channels/{_q(channel_id)}", idempotent=True)
+
+
+def test_alert_channel(channel_id: str) -> Request:
+    # Not idempotent: a resend sends a second test message.
+    return Request("POST", f"/v1/alert-channels/{_q(channel_id)}/test")

workly/_signing.py

@@ -0,0 +1,99 @@
+"""Delivery signatures. Must match internal/signing in the server:
+
+    Workly-Timestamp: <unix seconds>
+    Workly-Signature: v1=<hex HMAC-SHA256 of "<timestamp>.<body>">
+
+Several comma-separated signatures may be sent during key rotation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import time
+from collections.abc import Mapping
+from datetime import timedelta
+
+from ._errors import SignatureVerificationError
+
+HEADER_SIGNATURE = "Workly-Signature"
+HEADER_TIMESTAMP = "Workly-Timestamp"
+
+DEFAULT_TOLERANCE = timedelta(minutes=5)
+
+
+def sign(body: bytes | str, secret: str | bytes, timestamp: int | None = None) -> dict[str, str]:
+    """Return the signature headers Workly would send with `body`.
+
+    Useful for testing your endpoint without a server.
+    """
+    ts = int(time.time()) if timestamp is None else timestamp
+    return {
+        HEADER_TIMESTAMP: str(ts),
+        HEADER_SIGNATURE: "v1=" + _mac(_bytes(secret), ts, _bytes(body)).hex(),
+    }
+
+
+def verify_signature(
+    body: bytes | str,
+    headers: Mapping[str, str],
+    secret: str | bytes | None = None,
+    *,
+    tolerance: timedelta | float | None = DEFAULT_TOLERANCE,
+) -> None:
+    """Check that a delivery came from Workly. Raises SignatureVerificationError if not.
+
+    Pass the raw request body, exactly as received (not re-serialized JSON),
+    and the request headers. `secret` defaults to `WORKLY_SIGNING_SECRET`.
+    `tolerance` is how old the timestamp may be, which limits replays; None
+    skips the check.
+    """
+    if secret is None:
+        secret = os.environ.get("WORKLY_SIGNING_SECRET")
+        if not secret:
+            raise ValueError("pass secret or set WORKLY_SIGNING_SECRET")
+
+    signature = _header(headers, HEADER_SIGNATURE)
+    timestamp = _header(headers, HEADER_TIMESTAMP)
+    try:
+        ts = int(timestamp or "")
+    except ValueError:
+        raise SignatureVerificationError("missing or malformed signature headers") from None
+    if not signature:
+        raise SignatureVerificationError("missing or malformed signature headers")
+
+    if tolerance is not None:
+        seconds = tolerance.total_seconds() if isinstance(tolerance, timedelta) else tolerance
+        if seconds > 0 and abs(time.time() - ts) > seconds:
+            raise SignatureVerificationError("timestamp outside tolerance")
+
+    want = _mac(_bytes(secret), ts, _bytes(body))
+    for part in signature.split(","):
+        scheme, _, value = part.strip().partition("=")
+        if scheme != "v1":
+            continue
+        try:
+            got = bytes.fromhex(value)
+        except ValueError:
+            continue
+        if hmac.compare_digest(got, want):
+            return
+    raise SignatureVerificationError("signature does not match")
+
+
+def _mac(secret: bytes, timestamp: int, body: bytes) -> bytes:
+    return hmac.new(secret, f"{timestamp}.".encode() + body, hashlib.sha256).digest()
+
+
+def _bytes(value: str | bytes) -> bytes:
+    return value.encode() if isinstance(value, str) else value
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    # Framework header objects are case-insensitive; plain dicts may not be.
+    value = headers.get(name)
+    if value is None:
+        lower = name.lower()
+        value = next((v for k, v in headers.items() if k.lower() == lower), None)
+    return value

workly/_transport.py

@@ -0,0 +1,59 @@
+"""Retry and response handling shared by the sync and async clients."""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import Any
+
+import httpx
+
+from ._errors import APIConnectionError, api_error
+from ._requests import Request
+
+# Gateway errors, retried for requests that are safe to repeat. A 429 is
+# retried for every request: the server refused it without doing anything.
+_GATEWAY_STATUSES = frozenset({502, 503, 504})
+_MAX_DELAY = 8.0
+
+
+def retry_after_error(req: Request, exc: httpx.TransportError) -> bool:
+    # A request that never connected can always be resent; anything else
+    # may have reached the server.
+    if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)):
+        return True
+    return req.idempotent
+
+
+def retry_after_status(req: Request, response: httpx.Response) -> bool:
+    status = response.status_code
+    return status == 429 or (req.idempotent and status in _GATEWAY_STATUSES)
+
+
+def delay(attempt: int, response: httpx.Response | None = None) -> float:
+    if response is not None:
+        try:
+            retry_after = float(response.headers.get("Retry-After", ""))
+        except ValueError:
+            retry_after = math.nan  # absent, or an HTTP date
+        if retry_after >= 0:  # False for NaN
+            return min(retry_after, _MAX_DELAY)
+    return min(0.5 * 2**attempt, _MAX_DELAY) * random.uniform(0.5, 1)
+
+
+def connection_error(req: Request, exc: httpx.TransportError) -> APIConnectionError:
+    return APIConnectionError(f"{req.method} {req.path}: {exc!r}")
+
+
+def decode(response: httpx.Response) -> Any:
+    if response.status_code >= 400:
+        code, message = "unknown", response.text or response.reason_phrase
+        try:
+            err = response.json()["error"]
+            code, message = err["code"], err["message"]
+        except (ValueError, KeyError, TypeError):
+            pass
+        raise api_error(response.status_code, code, message)
+    if response.status_code == 204 or not response.content:
+        return None
+    return response.json()

workly-0.1.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: workly
+Version: 0.1.0
+Summary: Python SDK for Workly, the open-source HTTP task queue
+Keywords: task queue,background jobs,webhooks,http
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.27,<1
+Requires-Dist: workly-cli ; extra == 'cli'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://workly.run
+Project-URL: Repository, https://github.com/worklydev/workly
+Provides-Extra: cli
+Description-Content-Type: text/markdown
+
+# Workly for Python
+
+The Python SDK for [Workly](https://github.com/worklydev/workly), the open-source HTTP task queue. Enqueue a task, and Workly delivers it to your endpoint over HTTP, retrying with backoff until it succeeds.
+
+```sh
+pip install workly          # the SDK
+pip install "workly[cli]"   # the SDK plus the workly binary, for `workly dev`
+```
+
+Requires Python 3.11+. The only dependency is [httpx](https://www.python-httpx.org). The `cli` extra adds [`workly-cli`](https://pypi.org/project/workly-cli/), the server binary (about 7 MB), which you usually want on dev machines and not in production images.
+
+## Quickstart
+
+Start a local server with `workly dev` (SQLite, no auth, on :7337), then:
+
+```python
+from workly import Workly
+
+client = Workly()  # WORKLY_URL, else http://localhost:7337; WORKLY_API_KEY
+task = client.tasks.enqueue(
+    "emails",
+    url="https://api.example.com/send-email",
+    payload={"user_id": 123},
+)
+print(task.id, task.state)
+```
+
+Your endpoint receives a `POST` with the JSON payload. Any 2xx marks the task succeeded. A 5xx, 408, 429, timeout or connection error is retried with backoff. Delivery is at-least-once, so make handlers safe to run twice. `Workly-Task-Id` is stable across attempts and works as a deduplication key.
+
+## Verifying deliveries
+
+Every delivery is signed: with the server's `WORKLY_SIGNING_SECRET` when you run Workly yourself, or with your workspace's secret on [workly.run](#hosted-workly). Check the signature against the **raw** body:
+
+```python
+from workly import SignatureVerificationError, verify_signature
+
+
+# Flask
+@app.post("/send-email")
+def send_email():
+    try:
+        verify_signature(request.get_data(), request.headers)  # secret from WORKLY_SIGNING_SECRET
+    except SignatureVerificationError:
+        abort(401)
+    ...
+
+
+# FastAPI / Starlette
+@app.post("/send-email")
+async def send_email(request: Request):
+    verify_signature(await request.body(), request.headers, secret)
+    ...
+```
+
+By default, signatures older than 5 minutes are rejected (`tolerance=`). `workly dev` signs with `workly-dev-secret`. To test your handler without a server, use `workly.sign(body, secret)`, which returns the headers Workly would send.
+
+## Hosted Workly
+
+On [workly.run](https://workly.run), point the client at the hosted API and use the keys from the [console](https://console.workly.run):
+
+```sh
+export WORKLY_URL=https://api.workly.run
+export WORKLY_API_KEY=...                # API keys page
+export WORKLY_SIGNING_SECRET=whsec_...   # same page; each workspace has its own
+```
+
+Nothing else changes. Hosted workspaces have a request rate limit and a monthly task quota: requests over the rate limit are retried for you, and an enqueue over the quota raises `PermissionDeniedError` with the code `quota_exceeded`.
+
+## Tasks
+
+```python
+from datetime import datetime, timedelta, timezone
+
+client.tasks.enqueue(
+    "emails",
+    url="https://api.example.com/send-email",
+    payload={"user_id": 123},  # JSON; or body="raw text", content_type="text/csv"
+    method="POST",  # default
+    headers={"X-Tenant": "acme"},  # sent with every delivery
+    delay_seconds=60,  # or run_at=datetime(..., tzinfo=timezone.utc)
+    idempotency_key="welcome-123",  # an existing task with this key is returned instead
+    max_attempts=5,  # overrides the queue's setting
+    timeout_seconds=10,  # likewise
+)
+
+# Up to 100 at once, all or nothing.
+client.tasks.enqueue_many(
+    "emails",
+    [{"url": "https://api.example.com/send-email", "payload": {"user_id": i}} for i in range(100)],
+)
+
+task = client.tasks.get("task_01J9...")
+for attempt in client.tasks.attempts(task.id):
+    print(attempt.number, attempt.outcome, attempt.status_code, attempt.duration_ms)
+
+client.tasks.retry(task.id)  # run now; replays a finished task
+delivery = client.tasks.delivery(task.id)  # the signed request, to replay by hand
+client.tasks.cancel(task.id)
+
+# Newest first, across pages. All filters are optional.
+for task in client.tasks.list(
+    queue="emails", state="failed", created_after=datetime.now(timezone.utc) - timedelta(days=1)
+):
+    ...
+```
+
+## Queues
+
+Queues are created automatically on first enqueue. `put` sets a queue's configuration declaratively, which makes it easy to keep in code: settings you leave out are reset to their defaults.
+
+```python
+client.queues.put(
+    "emails",
+    max_attempts=10,
+    min_backoff_seconds=1,
+    max_backoff_seconds=3600,
+    backoff_multiplier=2,
+    timeout_seconds=30,
+    rate_per_second=50,
+    max_concurrency=20,
+)
+
+queue = client.queues.get("emails")
+print(queue.stats.due, queue.stats.oldest_due_at)
+
+client.queues.pause("emails")  # stop delivering; enqueueing still works
+client.queues.resume("emails")
+client.queues.cancel_pending("emails")  # cancel pending tasks
+client.queues.retry_failed("emails")  # replay failed tasks, e.g. after an outage
+for group in client.queues.failures("emails"):  # failed tasks grouped by error
+    print(group.count, group.error)
+client.queues.retry_failed("emails", last_error="HTTP 503 Service Unavailable")  # replay one group
+client.queues.activity("emails")  # succeeded/failed/cancelled in the last 7 days
+client.queues.delete("emails")  # delete the queue and all its tasks
+```
+
+## Schedules
+
+A schedule calls a URL on a cron timetable; each call is a run, retried and recorded like a task. Schedules are separate from queues. `put` is declarative, like `queues.put`. See [Schedules](https://docs.workly.run/schedules/).
+
+```python
+schedule = client.schedules.put(
+    "nightly-report",
+    cron="0 3 * * *",
+    timezone="Europe/Stockholm",
+    url="https://api.example.com/reports/nightly",
+    payload={"kind": "daily"},
+    max_attempts=3,
+    overlap="skip",  # skip a slot while the previous run is still going
+)
+print(schedule.next_runs)  # the next five times
+
+run = client.schedules.trigger("nightly-report")  # run it now
+for run in client.schedules.runs("nightly-report", state="failed"):
+    print(run.id, run.scheduled_for, run.last_error)
+client.runs.attempts(run.id)
+client.runs.retry(run.id)  # deliver it again, e.g. a failed or skipped run
+client.schedules.pause("nightly-report")
+client.schedules.resume("nightly-report")  # from the next scheduled time
+client.schedules.delete("nightly-report")  # with all its runs
+```
+
+Runs are delivered with `Workly-Run-Id`, `Workly-Schedule` and `Workly-Scheduled-For` headers and the same signature, so `verify_signature` works unchanged.
+
+## Async
+
+`AsyncWorkly` has the same methods, as coroutines:
+
+```python
+from workly import AsyncWorkly
+
+async with AsyncWorkly() as client:
+    task = await client.tasks.enqueue("emails", url="...", payload={"user_id": 123})
+    async for task in client.tasks.list(queue="emails"):
+        ...
+```
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `BadRequestError` | 400, invalid request |
+| `AuthenticationError` | 401, missing or wrong API key |
+| `PermissionDeniedError` | 403, not allowed, or a hosted limit was reached (e.g. `quota_exceeded`) |
+| `NotFoundError` | 404, no such queue or task |
+| `ConflictError` | 409, e.g. retrying a running task |
+| `PayloadTooLargeError` | 413 |
+| `RateLimitError` | 429, still rate limited after the retries |
+| `APIError` | base class of the above; has `.status`, `.code` (stable) and `.message` |
+| `APIConnectionError` | the server couldn't be reached |
+
+Requests are retried up to `max_retries` times (2 by default), honouring `Retry-After`. A 429 is always retried, since the server refused the request without doing anything. Connection errors and 502–504 are retried for requests that are safe to repeat: an enqueue only when it has an `idempotency_key`, or when the connection failed before the request was sent.
+
+## License
+
+[Apache-2.0](https://github.com/worklydev/workly/blob/main/LICENSE)