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

# Credits and retries

> How credits work, how to buy them, and how to retry safely.

## Credit usage

Pricing is agreed individually with your team. Contact us for your account’s terms.

| Action                        | Credits |
| ----------------------------- | ------: |
| Read an existing article      |       1 |
| Generate a new article        |     100 |
| Update an article             |     100 |
| Poll a job or read its result |       0 |
| Check your balance            |       0 |

Generation and updates include the result. Reading on the website remains free.
All API keys for your customer account share one balance.
`GET /api/v1/credits` returns your current balance and account-specific terms and limits.

## Buy credits

```bash theme={null}
curl -X POST "$YCPEDIA_API_URL/api/v1/credits/checkout" \
  -H "Authorization: Bearer $YCPEDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credits":100}'
```

Open the returned `url` to pay. Credits appear after payment is confirmed; creating a checkout does not add credits. Check your balance before starting work.

## Retry safely

Send an `Idempotency-Key` on every generate or update request. Use a unique value for each intended operation, and reuse that value when retrying after a timeout or network error. This returns the original operation without another charge.

Reusing a key for another profile or operation returns `409`. To deliberately retry a failed job or request a new update, use a new key.

Each successful article GET costs 1 credit. For generated results, keep polling the free job endpoint instead. A completed job retains its original article snapshot; use the article endpoint when you need the latest version.

## Errors and limits

| Status | What to do                                                                   |
| ------ | ---------------------------------------------------------------------------- |
| `401`  | Check your API key.                                                          |
| `402`  | Buy credits before retrying.                                                 |
| `404`  | The profile or job is unavailable. A read does not generate it.              |
| `409`  | Wait for active work to finish, or correct a reused idempotency key.         |
| `422`  | Correct the request, including the required idempotency header.              |
| `429`  | Wait for the seconds specified in `Retry-After`.                             |
| `5xx`  | Retry with backoff; keep the same idempotency key for generation or updates. |

The default limit is **120 requests per minute per customer**, including free requests and all API keys. Error responses contain `detail`, either a message or validation details.

Generation and updates reserve credits upfront. Failed or cancelled jobs refund them; the job then reports `credits_charged: 0`.