> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Understand credits and recover requests

> Check a tool's maximum credit quote, understand reservation and final usage, and recover interrupted or pending requests without starting duplicate work.

Plyne tools use workspace credits for acquisition. Describe the tool for its billing policy and call `/plan` for the maximum quote at your chosen settings. Preserve the request body and key until the operation reaches a terminal result.

## Plan, reserve and settle

| Stage | What happens |
| - | - |
| Describe | Read the schema, base pricing and billing policy without acquisition. |
| Plan | Validate the input and inspect eligibility and the maximum quote. No provider call or credit reservation occurs. |
| Execute | The operation reserves the quoted credits before acquisition. Insufficient balance prevents new acquisition. |
| Pending | A long-running operation retains its reservation while unresolved. |
| Settle | Final charge follows the tool's accepted policy. Unused reserved credits return to the balance. |
| Replay | The same normalized request and key return the saved completed result without another acquisition charge. |

A displayed base price describes the tool's default settings. Limits and source-specific settings can change the quote. Use the current plan rather than multiplying a catalog price without reading the billing policy.

## Know the billing unit

| Unit | Read it as |
| - | - |
| `request` | The documented operation at its selected settings. |
| `page` | A bounded source call or result set; a continuation requires another operation. |
| `record` | Returned records according to the tool's billing policy. |

For example, [Search jobs](https://docs.plyne.ai/tools/search-jobs.md) reserves up to `limit` times its per-record rate and charges for returned jobs. Other tools bill in source blocks or use a fixed quote. Empty acquisition results are not universally free: [company enrichment](https://docs.plyne.ai/tools/enrich-company.md) explicitly bills completed and not-found lookups. Read the policy of the tool you call.

`usage.credit_units` is the integer ledger amount and `usage.credits` is its credit representation. These are Plyne credits, not the upstream service's units.

## Keep one key per operation

Execute uses the `Idempotency-Key` header. MCP uses `idempotency_key` inside the tool arguments. A key contains 8–128 ASCII letters, digits, underscores or hyphens.

Keep both the original request body and key. Reuse them to retrieve that operation, including after a client disconnect. A new logical acquisition or a subsequent page needs a new key. Reusing an existing key with a different normalized request produces an `idempotency_conflict`.

## Recover an interrupted call

**1. Keep the original request**

A timeout, missing response or unavailable connection does not prove that no paid work started. Retain the same body and key.

**2. Retrieve the same operation**

Call execute again with the original body and key. A completed operation returns its saved result. A pending operation can return its current progress.

**3. Inspect the status**

For `pending` or `in_progress`, keep the operation identity. An unresolved provider acceptance may require reconciliation; do not create a replacement key merely to force another attempt.

**4. Start new work deliberately**

Use a new key when you intend a separate acquisition, rather than as a retry for an operation whose outcome is still unknown.

## Separate request errors from tool outcomes

An HTTP error has a `code` and `message`. A valid execution response also carries a tool `status`, so HTTP 200 alone does not mean data was found.

| Status | What to inspect |
| - | - |
| `completed` | Read data, sources and final usage. |
| `partial` | Check whether data is usable and inspect the tool's billing policy. |
| `not_found` | No matching usable result was returned; consult the specific billing policy. |
| `pending` | Retrieve the same operation; credits can remain reserved. |
| `failed` | Inspect the error and usage. A terminal tool failure is distinct from an interrupted HTTP response. |

See [source chains](https://docs.plyne.ai/guides/source-chains.md) for fallback behavior and [tool execution](https://docs.plyne.ai/tools/overview.md) for pagination and the shared response envelope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.