Skip to content Discuss your data requirements with our team. Get in touch ↗Discuss your data requirements with our team. Get in touch ↗

For AI agents: the documentation index is /docs/llms.txt, and this page is available as Markdown.

Errors

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

{
  "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 400 Fix the request
invalid_key 401 Fix the key
scope_missing 403 Use a key with the scope
not_found 404 Check the ID or address
insufficient_balance 402 Top up, then retry
spend_limit_exceeded 402 Raise the key's cap, or wait for the month to turn
max_cost_too_low 402 Raise max_cost_usd, or narrow the request
rate_limited 429 Wait retry_after seconds
idempotency_conflict 409 Wait for Retry-After, then retry
internal_error 500 Retry with backoff
service_unavailable 503 Retry with backoff

The dashboard adds billing_unavailable; /v1 calls never return it.

Fix the request

Retrying these as they are won't help.

invalid_request

  1. 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

  1. 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.

scope_missing

  1. 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

  1. 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 or find.

Top up or raise a limit

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

insufficient_balance

  1. 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

  1. 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

  1. 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

  1. You've hit one of your plan's rate limits. 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

  1. 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

  1. Something went wrong on West Kite's side. Retry with backoff. If it keeps happening, send the request_id to support.

service_unavailable

  1. 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

  1. Payments aren't set up where this ran, so a top-up, plan change or auto-recharge from the dashboard can't go through. Retrying won't help until payments are configured.