Errors - Klint

Every non-2xx response is the same compact RFC 9457 problem object (Content-Type: application/problem+json). Klint trims it to the fields an agent acts on:

{
  "type": "https://api.tryklint.ai/problems/validation-failed",
  "status": 422,
  "request_id": "req_example_41",
  "detail": "One request field needs correction.",
  "errors": [
    {
      "pointer": "#/post/filters/format",
      "reason": "INVALID",
      "detail": "Filters must be operator objects, not bare values."
    }
  ]
}

Field	Meaning
`type`	The absolute URI for this problem type, one URI per type. It resolves to the type’s documentation. Branch on this exact string, not on `detail`.
`status`	The HTTP status, repeated in-body
`request_id`	This response’s correlation ID, the same one the success envelope returns. Quote it when you report an issue.
`detail`	What happened this time and a safe correction. Human guidance. Do not parse it for control flow.

There is no separate code, docs_url, or is_retriable field. The type URI is both the identifier you branch on and the link to its docs. Retry guidance lives in the catalog below and in the Retry-After header. A validation-failed response adds an errors[] array. Each entry names the issue’s pointer, reason, and correction. See what gets rejected for the canonical examples, including candidates suggestions on unknown classification IDs.

The catalog

Each row’s type is the absolute URI https://api.tryklint.ai/problems/<slug>. The slug shown below is its last path segment and the name the docs use. Branch on the full type string.

The Retry column is authoritative; don’t infer retryability from the status code. Two 4xxs below retry differently than their status suggests.

Problem type	Status	Retry identical request?	Notes
`malformed-request`	400	No	Body isn’t valid JSON or structurally readable
`authentication-required`	401	No	Fix the key. See Authentication
`permission-denied`	403	No	Key lacks access to this operation
`insufficient-credits`	403	No	Top up, then retry
`not-found`	404	No	Malformed or unknown resource key
`not-tracked`	404	No	Valid key, outside what Klint tracks (see below)
`method-not-allowed`	405	No
`expired-cursor`	410	No, start a new search	See pagination
`payload-too-large`	413	No	Includes enforced `max_bytes`
`unsupported-media-type`	415	No	Send `application/json`
`validation-failed`	422	No	Fix the issues in `errors[]`
`rate-limit-exceeded`	429	Yes, after `Retry-After`
`internal-error`	500	Sometimes, retry once with backoff	Report with the `request_id`
`temporarily-unavailable`	503	Yes, with backoff
`request-timeout`	504	Yes, with backoff

The catalog may gain types before contract freeze and is deliberately non-exhaustive at the edges. If you hit an undocumented error, report it with its request_id.

`not-tracked` deserves a careful read

{
  "type": "https://api.tryklint.ai/problems/not-tracked",
  "status": 404,
  "request_id": "req_example_51",
  "detail": "ig_post_7q9zz is a valid Post key but is not in what Klint tracks. This does not claim the post is absent from Instagram."
}

It says only that Klint does not track this resource. It never says that the post or account is absent from Instagram. Don’t let an agent conclude “this post doesn’t exist” from a not-tracked.

Retrying 429s

{
  "type": "https://api.tryklint.ai/problems/rate-limit-exceeded",
  "status": 429,
  "request_id": "req_example_53",
  "detail": "Too many requests. Retry after the delay in Retry-After."
}

The Retry-After header is authoritative. Wait that long. Do not guess:

import os, time, requests

def klint_post(url, body, max_attempts=5):
    for attempt in range(max_attempts):
        resp = requests.post(
            url,
            headers={"Authorization": f"Bearer {os.environ['KLINT_API_KEY']}"},
            json=body,
        )
        if resp.status_code != 429:
            return resp
        time.sleep(int(resp.headers.get("Retry-After", 2 ** attempt)))
    return resp

async function klintPost(url: string, body: unknown, maxAttempts = 5) {
  let resp: Response;
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    resp = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.KLINT_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    if (resp.status !== 429) return resp;
    const wait = Number(resp.headers.get("Retry-After") ?? 2 ** attempt);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  return resp!;
}

For 503/504, use the same loop with exponential backoff when the response has no Retry-After header. Never auto-retry 4xxs other than 429. They fail identically until the request changes.

Across surfaces

The SDK throws one KlintApiError that carries the typed problem object. Branch on problem.type. MCP tool failures preserve the complete problem object as structured data. The CLI prints a summary and, in JSON mode, writes the exact problem object to stderr. No surface invents its own error dialect.

​The catalog

​not-tracked deserves a careful read

​Retrying 429s

​Across surfaces

The catalog

`not-tracked` deserves a careful read

Retrying 429s

Across surfaces