Errors

What this is: the one shape every error has, and the list of types. When you need it: writing the except / catch around any call.

curl

curl -i "$TASKADENCE_API_URL/v1/tasks/T0000000" \
  -H "Authorization: Bearer $TASKADENCE_TOKEN"

Python

from taskadence import InsufficientScopeError, NotFoundError, TaskadenceError

try:
    tm.tasks.read("T0000000")
except NotFoundError:
    ...
except InsufficientScopeError as exc:
    print("this token needs", exc.required_scope)
except TaskadenceError as exc:
    print(exc.status, exc.type, "— quote request_id", exc.request_id)

tm

tm tasks get T0000000
# exit code 1; the problem is printed with its request_id

The shape

Every error is application/problem+json (RFC 9457):

Field	Type	Meaning
type	string	about:blank or a urn:taskadence:problem:* identifier
title	string	e.g. "Forbidden"
status	integer	e.g. 403
detail	any	Human-readable explanation (a string; for a 422, the list of validation errors)
instance	string	e.g. "/v1/tasks/T123"
request_id	string	e.g. "9b2f1c1e-8c1a-4a53-9f9e-0f5f1f2d7c11"
errors (optional)	array	Structured failures: validation errors, or {loc, msg, allowed} for a bad parameter
mfa (optional)	object	On an mfa-required problem only: enrolled (does the person have an authenticator app set up), required_for (all or admins) and reason (org_policy: the organization's requirement; step_up: this action needs a second step)

Branch on status and type. Show detail to people. When you ask for help, quote request_id — it is also the X-Request-ID response header.

Problem types

Status	type	What happened — and what to do
any	about:blank	A plain HTTP error; the status and detail say everything.
422	…:validation	The request body or query did not validate. errors lists each failure (loc, msg, type).
400	…:invalid-parameter	A query parameter is outside what the operation accepts; errors[].allowed lists the valid values.
412	…:precondition-failed	If-Match did not match the resource's current ETag - re-read it and retry.
422	…:idempotency-key-reused	This Idempotency-Key was first used for a different request (method, path or body).
409	…:idempotency-key-in-flight	The first request with this Idempotency-Key has not finished; retry shortly.
400	…:idempotency-key-invalid	Idempotency-Key must be 1–255 printable ASCII characters.
429	…:rate-limit	Too many requests with this access token, or a signed-in user, or an address; wait Retry-After seconds (X-RateLimit-* say where you stand).
500	…:internal	An unexpected server error. Quote request_id to support.
401	…:token-invalid	The access token is unknown or malformed (or its principal no longer exists).
401	…:token-expired	The access token is past its expires_at; mint a new one.
401	…:token-revoked	The access token was revoked (by its owner, an admin, a rotation, or its service account's deactivation).
403	…:insufficient-scope	The access token does not carry the scope this operation needs (errors[0].required; null = not available to tokens).
403	…:test-token-read-only	A tkd_test_ token can authenticate and read, never write.
403 · 422	…:token-policy	The organization's token policy refuses this token (personal tokens off, expiry required, or past the maximum lifetime).
422	…:url-refused	The webhook URL is refused: not https, carries credentials, or resolves to a private, loopback, link-local, metadata, multicast or reserved address (errors[0].reason).
403 · 409	…:mfa-required	The organization requires two-step sign-in and this session signed in with one step. mfa.enrolled says whether the person has an authenticator app set up (sign in with it) or must set one up first; mfa.required_for is all or admins. Access tokens are not affected.
403	…:email-unverified	The signed-in person has not confirmed their email address yet. Confirm it from the email that was sent (or ask for a new one), then retry. Access tokens are not affected.
413	…:upload-too-large	The file is over the size limit (detail names it): 25 MB for attachments and project files, 2 MB for an avatar. A zip whose contents unpack to over 10 times the limit counts as too large.
415	…:upload-type-not-allowed	The file's type is not allowed (detail lists the allowed types). Executables, scripts, HTML, SVG, XML and macro-enabled Office files are never accepted, nor a zip holding one.
415	…:upload-type-mismatch	The file's contents are not what its extension (or its declared content type) says, for example an executable named .png, or a .txt that is not UTF-8 text.
422 · 503	…:upload-rejected	The malware scan refused the file (422), or could not scan it right now (503: retry later).

…: is urn:taskadence:problem:. Match on the identifiers, not on title or detail; responses from before the rename used urn:tasksmate:problem: (see the changelog).

The Python SDK raises one exception class per type (Python SDK → Errors).