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
- A parameter is missing, unknown or out of range, a
whereclause can't be read, the body isn't a JSON object, or anIdempotency-Keywas 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
- The key is missing, isn't a West Kite key, or no longer works.
reasonsays which:unknown(no key, or not one of ours),revoked(revoked, or rolled and past its grace period) orexpired(past the date set on it). Send a current key asAuthorization: Bearer <key>. See API keys.
scope_missing
- The key doesn't have the scope this call needs:
researchfor owner research,contactsfor contacts. Use a key that has it, or add the scope in the dashboard.
not_found
- 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
- Your balance can't cover the call's highest possible price.
balance_usdandavailable_usdsay what's there, andupgrade_urlis where to top up. Top up, turn on auto-recharge, or lower the price with a smallerlimit.
spend_limit_exceeded
- The key has reached its monthly spend cap.
spend_cap_usdandspent_usdsay 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
- The call costs more than the
max_cost_usdyou sent. The price is inquoted_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
- You've hit one of your plan's rate limits.
reasonsays which:requests(this minute) orconcurrency(too many at once). Waitretry_afterseconds. Owner research never gets this for concurrency: extra runs queue.
idempotency_conflict
- A request with the same
Idempotency-Keyis still running. Wait for theRetry-Afterheader, usually a couple of seconds, and send it again; you'll get the saved answer once the first finishes.
internal_error
- Something went wrong on West Kite's side. Retry with backoff. If it keeps happening, send the
request_idto support.
service_unavailable
- 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
- 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.