# Errors

Every error body has the same three fields.

```json
{
  "error": {
    "code": "invalid_limit",
    "message": "limit must be between 1 and 200",
    "retryable": false
  }
}
```

- **`code`** is for your program. It does not change.
- **`message`** is for a reader. It is written to be relayed to an owner.
- **`retryable`** says whether the same request can succeed later.

Read `retryable` rather than guess from the status. A 502 from the hosting
backend can be either.

## The one extra field

A failed build carries a fourth field, `detail`, with the build log.

That log is the compiler telling whoever wrote the source what is wrong
with it. `detail` is for build logs and nothing else.

## Status and next action

A resource that is not finished the moment you ask for it carries two more
fields of its own:

- **`status`**, which says where it is;
- **`next_action`**, in plain language, which says what to do now.

Relay `next_action` to the owner. It is written for that.

## Codes you meet often

| Code | Means |
|---|---|
| `not_found` | no such thing, or none you may see |
| `invalid_json` | the body is not valid JSON for this endpoint |
| `body_too_large` | the body is over 1 MiB |
| `invalid_cursor` | use `next_cursor` from an earlier answer |
| `provider_error` | the hosting backend refused or failed |
| `internal` | a fault on Clave's side; retry |

## Nothing provider-shaped leaks

No `/v1` answer names the hosting provider, its identifiers or its error
strings. A `provider_error` says the hosting backend refused and stops
there.

Two answers carry a provider's address on purpose, because a payer's
browser has to land on it: a checkout URL and a portal URL.

## A message does not blame the wrong party

Clave works to keep each message about the party that can act on it. A
refusal names the consequence and the remedy for the surface you are on.

If a message sends you to fix something you did not break, that is a
defect here. Send it with `POST /v1/feedback`.

---

## Where this page sits

This is one page of the Clave documentation.
Read it as a web page at https://docs.heyclave.party/api/errors.
Every page has a `.md` address, and https://docs.heyclave.party/llms.txt lists them all.

- Previous: [Authentication](https://docs.heyclave.party/api/auth.md)
- Next: [Pagination](https://docs.heyclave.party/api/pagination.md)
- Index: [Overview](https://docs.heyclave.party/index.md)