API Error Catalog

Every Tasks Wiz API error is application/problem+json (RFC 7807). The type field links here, anchored on the machine-stable code. Branch on code, never on detail. Quote the request_id (also the X-Request-Id response header) when reporting an issue.

Example body:

{
  "type": "https://api.tasks-wiz.com/errors/task-not-found",
  "title": "Task not found",
  "status": 404,
  "code": "task_not_found",
  "detail": "No task with identifier 'abc-123' belongs to the caller.",
  "instance": "/tasks/abc-123",
  "request_id": "01HQ9X7M3E2VAFZ8N6KPYC4QR1"
}

Codes

code	status	meaning & recommended client behavior
validation_error	422	One or more fields failed validation; see the errors[] array (per-field field/code/detail). Fix inputs; do not retry unchanged.
unauthorized	401	Missing/invalid bearer token. Refresh the Cognito token and retry once.
forbidden	403	Authenticated but not allowed. Do not retry.
not_found	404	Route or resource does not exist.
task_not_found	404	No task with that id belongs to the caller (cross-tenant ids are reported as not-found by design).
export_not_found	404	No export job with that id for the caller.
method_not_allowed	405	HTTP method unsupported for this resource; see the Allow header.
conflict	409	Request conflicts with current state.
email_already_verified	409	Resend-verification called but the email is already verified. Nothing to do.
stale_resource	412	Optimistic-concurrency failure: your If-Match ETag is stale. Refetch the resource and retry with the new ETag.
precondition_failed	412	A required precondition was not met.
confirm_delete_required	428	DELETE /account needs X-Confirm-Delete: <your account email> to proceed (CSRF-by-accident guard).
idempotency_key_reused	422	Same Idempotency-Key with a different request body. Use a fresh key or send the original body.
batch_too_large	422	Batch exceeds 50 items. Split the request.
invalid_cursor	422	Pagination cursor is malformed or failed signature verification. Restart pagination without a cursor.
invalid_if_match	422	If-Match is not a valid ETag. Send the quoted ETag from the resource's last response, e.g. "v3".
invalid_scope	422	DELETE /account/data scope must be completed_tasks or activities.
invalid_older_than	422	older_than must look like 90d.
rate_limit_exceeded	429	Per-user rate limit hit. Honor Retry-After and the X-RateLimit-* headers; back off.
verification_already_sent_today	429	A verification email was already sent today. Try again tomorrow.
internal_error	500	Unexpected server error (no stack trace leaked). Retry with backoff; if it persists, report the request_id.