Errors and fixes

Inklate’s errors are written to be acted on, and every machine-readable part of them is stable. This page is the full catalog: what a failed request looks like on each door, the reason slugs you can branch on, the validation codes that appear inside a successful post response, the five fix kinds and their parameters, and the upgrade markers on plan refusals.

Two places errors appear

1. Request errors — the call itself was refused (bad input, missing auth, rate limit). REST returns a non-2xx status with the one error envelope; MCP returns the same facts as a prefixed text line.
2. Validation errors — the call succeeded (a draft with problems saves fine) and the response’s per-channel errors[] tell you what would stop publishing. These never use HTTP status; read them off the 2xx response.

The bridge between the two: arming (setting a scheduled_at or publishing) a post that isn’t ready is refused as a request error — 400 BAD_REQUEST with reason: "not_ready" — and the whole write rolls back.

The refusal answers with the post it refused. You do not need a second call to find out why: the error carries the same post object a successful call would have returned, per-channel errors[] and machine fixes[] included. On a refused create its id is null, because the rollback means nothing was stored; on a refused update or publish the id is real and the post still stands at its previous state.

Request errors: one code table, every door

Every refusal maps through one kind→status table, so the same failure reads the same over REST, MCP, and the CLI:

REST envelope:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "This post has 2 channels that are not ready — fix the errors first",
    "reason": "not_ready",
    "request_id": "req_…",
    "post": {
      "id": null,
      "ready": false,
      "channels": [
        {
          "channel_id": "ch_…",
          "provider": "x",
          "ready": false,
          "errors": [
            {
              "code": "validation",
              "field": "content",
              "message": "319 characters is over X's 280 limit",
              "fixes": [{ "kind": "trim_to_fold", "label": "Trim to 280", "max_length": 280 }]
            }
          ]
        }
      ]
    }
  }
}

error.post appears only on refusals that were decided by inspecting a post — today, arming. Every other refusal omits it.

Over MCP the same facts ride inline, so an agent parses a slug, not prose. The post follows the marker line as plain JSON:

BAD_REQUEST: This post has 2 channels that are not ready — fix the errors first [reason:not_ready]
{
  "id": null,
  "ready": false,
  "channels": [ … ]
}

The bracket marker carries reason:<slug>, index:<n> (which entry of a batch input failed), and retry_after_ms:<n> when present. The CLI exits 4 on any typed refusal, prints the same per-channel ✓/✗ summary a successful write prints, and puts the full refusal — error.post included — on stdout.

Reason slugs

reason is the finer machine slug on a request error, present where one exists:

Media failure reasons

An uploaded or URL-ingested file that fails carries error.reason on the file object (and failed: true in a post response’s media[] entry). The reasons are a closed set:

All of them are terminal: remove or replace the file. A file that is merely still processing is not an error — wait, then re-check.

Validation codes on post responses

Every post response (create, update, get, validate) carries channels[], each with ready and errors[]. An error is:

{
  "code": "validation",
  "field": "content",
  "message": "Text is 312 characters — X allows 280",
  "fixes": [{ "kind": "trim_to_fold", "label": "Trim to 280 characters", "max_length": 280 }]
}

code is the verdict category, field names the input to change, message carries the real numbers, and fixes the machine repairs where any exist.

Only a validation refusal carries fixes — a policy refusal (quiet_hours, banned_term, blocked_link) names the rule but has no automatic repair. Soft issues arrive separately as warnings[] (codes: truncated, dropped_media, missing_media, dropped_mark, flattened_link) and never block publishing.

The five fix kinds

A fix is a machine repair, discriminated on kind. Applied server-side when autofix is on (the default); a caller preferring manual control writes the fixed content via per_channel.

Every kind also carries a human label (what the composer puts on the button). Fixes that were applied by autofix are reported in the response’s fixes_applied (channel_id, provider, kind). An applied fix marks that channel copy authored, so a later story edit never silently discards it.

Upgrade markers: [upgrade:<kind>]

A plan-limit refusal is always FORBIDDEN (403), and its message ends with a structured suffix an agent can parse — "… [upgrade:seats]":

Billing is read-only for agents: billing_plan and billing_ink report state over MCP, but checkout and top-ups happen in the dashboard, by a person.