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

# Error codes

> Every code the API can return, what causes it, and whether retrying helps.

Every failure is the same envelope, and `docsUrl` on it points at the anchor on this page.

```json theme={null}
{
  "error": {
    "code": "no_delegation",
    "message": "No nameservers are delegated for acme.com.",
    "docsUrl": "https://docs.ownsi.dev/errors#no_delegation"
  }
}
```

Branch on `code`. It is an identifier and will not be reworded. `message` is written for a person and
may change.

<Note>
  These are **transport** errors — the request could not be answered. They are a different thing
  from a [diagnosis](/diagnostics/catalogue), which is a successful `200` telling you what is wrong
  with a DNS record.
</Note>

## invalid\_domain

**400.** What you sent is not a domain name that can be read or claimed — empty, not a hostname, or
longer than 253 characters.

Retrying does not help. The `message` says which of the three it was.

## no\_delegation

**404.** The name resolves to no nameservers at all. Usually the domain is not registered, or it was
registered minutes ago and the registry has not published the delegation yet.

Retrying does not help until the registration goes through.

## unresolvable

**502.** ownsi could not reach DNS to read the zone. This is ours, not yours.

<Check>Safe to retry, with a backoff.</Check>

## unauthenticated

**401.** No valid session on the request. Everything under `/api/domains`, `/api/claims` and
`/api/verifications` needs one; see [Authentication](/api-reference/authentication).

Retrying the same request does not help. Sign in and retry.

## already\_claimed

**409.** The domain already has a claim open on your account, with the token it was issued. This is
not a conflict with another account — [that is coexistence](/concepts/claim-lifecycle#coexistence)
and it is not an error.

Use the claim you already have. The token on it is the one that will verify.

## claim\_ended

**409.** The claim has ended — proved, expired or canceled — and an ended claim takes no action.
Its token is no longer accepted, so there is nothing to re-check.

Claim the domain again. That opens a new claim with a new token, and the ended one stays as
history.

## domain\_not\_found

**404.** No domain with that id belongs to your account. The same code is returned whether the
domain does not exist or belongs to someone else, deliberately — an id lookup should not confirm
that someone else's domain exists.

## claim\_not\_found

**404.** No claim with that id belongs to your account. As with `domain_not_found`, the same code
comes back whether the claim does not exist or belongs to someone else.

## verification\_not\_found

**404.** No verification with that id belongs to your account. A verification is reachable from the
`verificationId` on the claim that started it.

## verification\_not\_running

**409.** The verification has finished — its claim was proved, the window closed, or the claim was
canceled — so there is nothing left to run.

Claim the domain again. That opens a new claim with a new token and a verification of its own.

## claim\_not\_proved

**404.** No proved claim with that id belongs to your account. A proof link shares a proof, so
there is nothing to publish until one is granted — and a pending, expired or canceled claim never
had one.

## proof\_link\_not\_found

**404.** No link with that slug was ever published on that claim. Revoking one twice returns this
too: what is already taken back is no longer there to take back.

## rate\_limited

**429.** Too many requests. Carries a `Retry-After` header in seconds.

Enforced per IP on the public surfaces — reading a zone, and public proof pages — and per
verification on `POST /api/verifications/:id/runs`.

<Check>Safe to retry after `Retry-After`. Forcing checks in a loop does not make DNS answer faster.</Check>

## Which ones are worth retrying

| Code                       | Status | Retry                             |
| -------------------------- | ------ | --------------------------------- |
| `invalid_domain`           | 400    | No — fix the input.               |
| `no_delegation`            | 404    | No — the domain is not delegated. |
| `unresolvable`             | 502    | Yes, with backoff.                |
| `unauthenticated`          | 401    | No — sign in first.               |
| `already_claimed`          | 409    | No — use the open claim.          |
| `claim_ended`              | 409    | No — claim the domain again.      |
| `domain_not_found`         | 404    | No.                               |
| `claim_not_found`          | 404    | No.                               |
| `verification_not_found`   | 404    | No.                               |
| `verification_not_running` | 409    | No — claim the domain again.      |
| `claim_not_proved`         | 404    | No — nothing is proved to share.  |
| `proof_link_not_found`     | 404    | No.                               |
| `rate_limited`             | 429    | Yes, after `Retry-After`.         |