# Errors

> Documentation index: [llms.txt](https://westkite.com/docs/llms.txt). Every page is also at its URL plus `.md`.

Errors come back with an HTTP status and one JSON shape. `retryable` says whether the same request can succeed later, and `docs_url` links to the code's section on this page.

## The error shape

```json 402
{
  "error": {
    "code": "insufficient_balance",
    "message": "The balance is too low for this call. Top up in the West Kite dashboard.",
    "retryable": false,
    "docs_url": "https://westkite.com/docs/api/errors#insufficient_balance",
    "balance_usd": 0.01,
    "available_usd": 0.01,
    "upgrade_url": "https://app.westkite.com/developers/billing"
  },
  "request_id": "req_3e0a…"
}
```

`request_id` sits beside `error` and in the `X-Request-Id` header. Branch on `code`, not on `message`: messages are for people and can change. Some codes add fields inside `error`:

| Code | Adds |
|---|---|
| `invalid_key` | `reason`: `revoked`, `expired` or `unknown` |
| `insufficient_balance` | `balance_usd`, `available_usd`, `upgrade_url` |
| `spend_limit_exceeded` | `spend_cap_usd`, `spent_usd` |
| `max_cost_too_low` | `quoted_usd` |
| `rate_limited` | `reason`: `requests` or `concurrency`; `retry_after`, `upgrade_url` |

Failed calls cost nothing.

## Codes

| Code | Status | What to do |
|---|---|---|
| [`invalid_request`](#invalid_request) | 400 | Fix the request |
| [`invalid_key`](#invalid_key) | 401 | Fix the key |
| [`scope_missing`](#scope_missing) | 403 | Use a key with the scope |
| [`not_found`](#not_found) | 404 | Check the ID or address |
| [`insufficient_balance`](#insufficient_balance) | 402 | Top up, then retry |
| [`spend_limit_exceeded`](#spend_limit_exceeded) | 402 | Raise the key's cap, or wait for the month to turn |
| [`max_cost_too_low`](#max_cost_too_low) | 402 | Raise `max_cost_usd`, or narrow the request |
| [`rate_limited`](#rate_limited) | 429 | Wait `retry_after` seconds |
| [`idempotency_conflict`](#idempotency_conflict) | 409 | Wait for `Retry-After`, then retry |
| [`internal_error`](#internal_error) | 500 | Retry with backoff |
| [`service_unavailable`](#service_unavailable) | 503 | Retry with backoff |

The dashboard adds [`billing_unavailable`](#billing_unavailable); `/v1` calls never return it.

## Fix the request

Retrying these as they are won't help.

### `invalid_request`

400. A parameter is missing, unknown or out of range, a `where` clause can't be read, the body isn't a JSON object, or an `Idempotency-Key` was reused with a different request. The message says what's wrong and what's allowed, such as the fields a find type takes.

### `invalid_key`

401. The key is missing, isn't a West Kite key, or no longer works. `reason` says which: `unknown` (no key, or not one of ours), `revoked` (revoked, or rolled and past its grace period) or `expired` (past the date set on it). Send a current key as `Authorization: Bearer <key>`. See [API keys](https://westkite.com/docs/api/authentication.md).

### `scope_missing`

403. The key doesn't have the scope this call needs: `research` for owner research, `contacts` for contacts. Use a key that has it, or add the scope in the dashboard.

### `not_found`

404. No record has that ID, the path is not an endpoint, no research is on file for a contact, an export link expired, or no public imagery covers a property for an image. Check the ID came from [search](https://westkite.com/docs/api/search.md) or [find](https://westkite.com/docs/api/find.md).

## Top up or raise a limit

Nothing was charged. An agent should stop and tell its person rather than retry.

### `insufficient_balance`

402. Your balance can't cover the call's highest possible price. `balance_usd` and `available_usd` say what's there, and `upgrade_url` is where to top up. Top up, turn on auto-recharge, or lower the price with a smaller `limit`.

### `spend_limit_exceeded`

402. The key has reached its monthly spend cap. `spend_cap_usd` and `spent_usd` say where it stands. Raise the cap in the dashboard or wait for the month to turn. Your other keys keep working.

### `max_cost_too_low`

402. The call costs more than the `max_cost_usd` you sent. The price is in `quoted_usd`. Raise the cap if it's acceptable, or narrow the request.

## Wait and retry

These clear on their own. Send the same `Idempotency-Key` when you retry, so you're never charged twice.

### `rate_limited`

429. You've hit one of your plan's [rate limits](https://westkite.com/docs/api/rate-limits.md). `reason` says which: `requests` (this minute) or `concurrency` (too many at once). Wait `retry_after` seconds. Owner research never gets this for concurrency: extra runs queue.

### `idempotency_conflict`

409. A request with the same `Idempotency-Key` is still running. Wait for the `Retry-After` header, usually a couple of seconds, and send it again; you'll get the saved answer once the first finishes.

### `internal_error`

500. Something went wrong on West Kite's side. Retry with backoff. If it keeps happening, send the `request_id` to [support](https://westkite.com/support.md).

### `service_unavailable`

503. West Kite or a source it depends on is briefly unavailable, such as when no aerial photo is available for an image right now. Retry with backoff.

## Dashboard only

### `billing_unavailable`

503. Payments aren't set up where this ran, so a top-up, plan change or auto-recharge from the [dashboard](https://app.westkite.com/developers) can't go through. Retrying won't help until payments are configured.
