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.
{
"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"
}| 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. Read the X-RateLimit-* headers and back off. There is no Retry-After header; the wait time is in the detail field. |
| 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. |