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

# Errors

> One shape, real status codes, and what 402 actually means.

Every failure is the same shape:

```json theme={null}
{ "error": "Your subscription is inactive. Existing links keep resolving, but you cannot create or edit links until you resubscribe." }
```

`error` is a sentence written for a person to read. It is not a code to switch
on — switch on the HTTP status.

## 402 does not mean your links stopped

This is the one worth reading twice.

<Warning>
  **`402` means this *action* needs payment.** It never means an existing code
  stopped resolving. Every link you have created keeps working in every account
  state, including cancelled — see [Permanence](/permanence). The message always
  says so explicitly; if you show it to a user, show all of it.
</Warning>

`402` appears in three distinct situations, told apart by the body:

| Situation                              | Body                                              |
| -------------------------------------- | ------------------------------------------------- |
| Machine-payment challenge              | has `pay`, `price`, `currency`, `docs`            |
| Allowance spent                        | `error` mentions your link limit or billing cycle |
| Subscription inactive or feature gated | `error` names the feature                         |

## Statuses

| Code  | Meaning                                                                                                        |
| ----- | -------------------------------------------------------------------------------------------------------------- |
| `400` | The body or query did not validate. `error` names the field.                                                   |
| `401` | Missing or invalid credentials.                                                                                |
| `402` | This action needs payment. See above.                                                                          |
| `403` | Authenticated, but not permitted — not the workspace owner, or at the seat cap.                                |
| `404` | No such resource **on this account**. We do not distinguish "does not exist" from "is not yours".              |
| `409` | A conflict: slug already taken, hostname already registered, payment already spent, account already has a key. |
| `410` | Resolution refused — the link was flagged for abuse.                                                           |
| `413` | Logo larger than 1 MB.                                                                                         |
| `415` | Logo is not PNG, JPEG, WebP or SVG.                                                                            |
| `422` | The destination failed a safety check.                                                                         |
| `429` | Too many writes this minute.                                                                                   |
| `502` | An upstream we depend on is unavailable. Retry.                                                                |

## Retrying

`429` and `502` are worth retrying with backoff. `502` from analytics means the
recent half of the window is unavailable — we return the error rather than the
older half alone, because a partial answer that looks complete is worse than a
failure you can retry.

Nothing else is worth retrying unchanged. A `409` on a payment means that
credential is spent; get a fresh `402`. A `400` on an x402 payment means the
requirements moved; get a fresh `402` rather than adjusting the numbers yourself.

## Creation is atomic

If creating a link returns an error, no link was created — quota checks bind
inside the insert rather than being read beforehand, so concurrent creates cannot
all slip past a limit. The same holds for machine payments: a settlement that
fails releases its claim and leaves nothing behind, so you can retry with a
working instrument.