Last updated 2026-10-25

Errors

Every error from /v1 has the same shape:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You're out of credits — this needs 40 and you have 10. Buy a credit pack at /pricing#packs (packs never expire) or upgrade your plan.",
    "status": 402,
    "docs_url": "https://kinsy.ai/docs/errors#insufficient_credits",
    "checkout_url": "https://kinsy.ai/pricing?src=api"
  }
}

code is stable and meant for programs; message is for people and may change. docs_url points at the section below. checkout_url appears only on 402; retry_after (seconds) only on 429.

Codes

bad_request

400. The request was understood but cannot be served as asked: an Idempotency-Key over 128 characters, a callback_url (not available yet), or an unknown file kind. Fix the request; do not retry it unchanged.

unauthorized

401. No bearer token, a malformed one, or a key that is unknown, revoked or expired. Check the header and the key in Settings → API keys. Keys are not accepted on the web app's own routes.

insufficient_credits

402. The call needs more credits than the account has. Nothing was started and nothing was charged. Send the person to checkout_url to buy a pack or a plan; retry the same call afterwards. An unverified account can also unlock the rest of its free credits by verifying its email.

forbidden

403. The deck belongs to another account.

not_found

404. No such deck, key or file. A deck that exists but belongs to another account answers 403 (see above); an id that was never created answers 404.

conflict

409. A build for this deck is still running, or the account already has 10 active keys. Wait, or revoke a key.

too_large

413. A file over 25 MB.

unsupported_media_type

415. A file type the extractor does not read. Supported: PDF, Word-style documents, Markdown and plain text, spreadsheets and CSV, images.

validation_error

422. A field is missing, empty, too long or out of range; message says which. POST /v1/decks and POST /v1/intake need a non-empty brief or at least one source.

rate_limited

429. Either the per-key limit (120 requests a minute) or an account backstop (15 builds a day, 40 edits an hour). Wait retry_after seconds, then retry. Do not retry a build in a tight loop; poll the status call instead.

unavailable

503. A dependency is briefly unavailable (the build queue, the key store) or builds are not enabled on this server. Retry with backoff; nothing was charged.

Build failures

A build that starts and then fails is not an HTTP error: GET /v1/decks/{id} answers 200 with status: "error" and a one-sentence error. The credits for that build are refunded automatically. Start a new build; if it fails again, contact support with the deck id.