# Fail a compliance task > The tasks.fail operation: POST /api/v1/tasks/{id}/fail in the REST API and the tasks_fail tool in the MCP server. Records that a task couldn't be done, with a `reason` (for example: the portal refused the application, a document is missing). The task becomes `failed` (`task.failed`) and its lease ends. With `retryAt`, it opens again on that date, unassigned, for another attempt; without one, it stays failed. Failing a task doesn't change the obligation: a registration's deadline escalations and automatic block continue (spec §10.3), and a filing period stays due. While someone holds the task's lease, only they can fail it. ## At a glance - **REST:** `POST /api/v1/tasks/{id}/fail` - **MCP tool:** `tasks_fail` - **Operation ID:** `tasks.fail` - **Scope:** Organization, or one of its legal entities or brands - **Permission:** `tasks:write` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `tasks:write` scope - **Since:** M10 ## Request ### Path parameters | Field | Type | Description | | ----- | ----------- | ----------- | | `id` | `task_…` ID | | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ----------------- | -------------------- | -------- | ------------------------------------------------------------------------ | | `reason` | string | Yes | Why the task couldn't be done. Data, shown to people and agents. | | `retryAt` | date-time | No | When the task opens again for another attempt (ISO 8601, in the future). | | `expectedVersion` | integer (at least 1) | No | | ## Response `200 OK` with a JSON object: | Field | Type | Description | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `id` | `task_…` ID | | | `object` | `"task"` | | | `type` | one of 12 values, e.g. `registration.prerequisites`, `registration.prepare`, `registration.submit` (all in the OpenAPI document) | | | `entityId` | `ent_…` ID | | | `livemode` | boolean | | | `regimeId` | string or null | | | `registrationId` | `regn_…` ID or null | | | `filingPeriodId` | `fp_…` ID or null | | | `prerequisiteCode` | string or null | | | `title` | string | | | `description` | string or null | | | `priority` | one of `low`, `normal`, `high`, `urgent` | | | `status` | one of `open`, `claimed`, `in_progress`, `awaiting_approval`, `done`, `failed`, `cancelled` | | | `reason` | one of 11 values, e.g. `auto_blocked`, `existing_customer_sale`, `prerequisite_open` (all in the OpenAPI document) or null | | | `dueAt` | date-time or null | | | `overdue` | boolean | | | `assignee` | object or null | | | `claimedUntil` | date-time or null | | | `leaseActive` | boolean | | | `completeWith` | one of `tasks.complete`, `tasks.submit` | | | `needsAuthorization` | boolean | | | `inputs` | array of object | | | `inputs[].kind` | string | | | `inputs[].fileId` | `file_…` ID or null | | | `inputs[].data` | object or null | | | `outputs` | object or null | | | `authorizationId` | `atz_…` ID or null | | | `approvalRequestId` | `apr_…` ID or null | | | `failure` | object or null | | | `checklist` | array of object | | | `checklist[].text` | string | | | `checklist[].done` | boolean | | | `createdAt` | date-time | | | `updatedAt` | date-time | | | `completedAt` | date-time or null | | | `completedBy` | string or null | | | `version` | integer (at least 1) | | ## Examples ### The portal is down; try again tomorrow ```http POST /api/v1/tasks/task_01m4ttwd3veh9apbewxheq5xa9/fail Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "reason": "The OSS portal returns a maintenance page.", "retryAt": "2026-10-16T08:00:00.000Z" } ``` Response (`200`): ```json { "id": "task_01m4ttwd3veh9apbewxheq5xa9", "object": "task", "type": "filing.submit", "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4", "livemode": true, "regimeId": "EU_OSS_UNION", "registrationId": "regn_01m4ttwd3veh9apbewxheq5xa8", "filingPeriodId": "fp_01m4ttwd3veh9apbewxheq5xa7", "prerequisiteCode": null, "title": "File the One-Stop Shop, Union scheme 2026-Q3 return", "description": "File the One-Stop Shop, Union scheme 2026-Q3 return with the authority using the filing package, by 2026-10-31. Then submit this task with the return's reference, the portal's confirmation and the authorization you acted under: the period becomes submitted.", "priority": "high", "status": "failed", "reason": "period_ended", "dueAt": "2026-10-31T22:59:59.000Z", "overdue": false, "assignee": { "type": "agent", "id": "agt_01m4ttwd3veh9apbewxheq5xa6" }, "claimedUntil": null, "leaseActive": false, "completeWith": "tasks.submit", "needsAuthorization": true, "inputs": [ { "kind": "filing_period", "fileId": null, "data": { "filingPeriodId": "fp_01m4ttwd3veh9apbewxheq5xa7", "regimeId": "EU_OSS_UNION", "periodKey": "2026-Q3", "dueDate": "2026-10-31", "dueAt": "2026-10-31T22:59:59.000Z" } }, { "kind": "filing_package", "fileId": null, "data": { "filingPeriodId": "fp_01m4ttwd3veh9apbewxheq5xa7" } }, { "kind": "playbook", "fileId": null, "data": { "regimeId": "EU_OSS_UNION", "playbookKind": "filing" } } ], "outputs": null, "authorizationId": null, "approvalRequestId": null, "failure": { "reason": "The OSS portal returns a maintenance page.", "retryAt": "2026-10-16T08:00:00.000Z", "failedAt": "2026-10-15T09:28:00.000Z", "failedBy": "agt_01m4ttwd3veh9apbewxheq5xa6" }, "checklist": [ { "text": "Download the filing package", "done": false }, { "text": "File the return in the authority's portal", "done": false }, { "text": "Submit this task with the reference, the confirmation and the authorization", "done": false } ], "createdAt": "2026-10-01T00:23:00.000Z", "updatedAt": "2026-10-15T09:28:00.000Z", "completedAt": "2026-10-15T09:28:00.000Z", "completedBy": "agt_01m4ttwd3veh9apbewxheq5xa6", "version": 3 } ``` ## Errors | Code | HTTP status | When | What to do | | ------------------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | No reason, or `retryAt` isn't in the future. | Fix the fields listed in `details.issues` and send the request again. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | No task with this ID in this organization, entity and mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`task_status_invalid`](https://ownrecord.io/docs/reference/errors.md#task_status_invalid) | 409 | The task is finished, or it waits for an approval. | Reload the task: finished tasks (`done`, `failed`, `cancelled`) don't change, and a task waiting for an approval changes only through that approval. `details.status` is the task's status. | | [`task_claimed`](https://ownrecord.io/docs/reference/errors.md#task_claimed) | 409 | Someone else holds the task's lease. | Work on another task (`tasks.list` with `claimable: true`), or try again after `details.claimedUntil`: an expired lease frees the task. `details.assignee` is who holds it. | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The task changed since `expectedVersion`, or at the same moment. | Fetch the object again and retry the change. | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't work on compliance tasks here. | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).