---
title: "Report the outcome of a leased effect"
method: POST
path: "/v1/effects/{effectId}/report"
tags: ["Effects"]
---

# Report the outcome of a leased effect

`POST /v1/effects/{effectId}/report`

## Request

- Base URL: `https://ratchetgate.com`
- URL: `https://ratchetgate.com/v1/effects/{effectId}/report`
- Auth: HTTP bearer

Closes out an effect you hold the lease for. Reporting "succeeded" records a result that later duplicate callers replay instead of re-running the action. Reporting "failed" asserts the action did not happen, which permits a fresh attempt.

## Path parameters

- `effectId` string, required

## Request body

- object
  - `lease_token` string, required
  - `outcome` 'succeeded' | 'failed', required: Report "failed" ONLY when you know the side effect did not reach the outside world. If you are unsure, report nothing and let the lease lapse — that records an honest `indeterminate`.
  - `result` unknown
  - `failure_reason` string
  - `actual_cost_micros` integer

## Response `200`

Default Response

- object
  - `effect_id` string
  - `state` string
  - `attempt` integer
  - `settled_at` string, nullable
  - `actual_cost_micros` integer

## Other responses

- `400`: Invalid request.
- `401`: Missing or invalid API key.
- `402`: Insufficient prepaid credit.
- `403`: Scope, policy, or budget refusal.
- `404`: Not found.
- `409`: Conflicting state or idempotency-key reuse.
- `413`: Payload too large.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/ratchetgate/apis/ratchet-api.md) · [All operations](https://skmtc.dev/ratchetgate/apis/ratchet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ratchetgate/apis/ratchet-api/revisions/5712f33c692f?raw)