Errors & limits

Error format#

{
  "error": "That time has already passed",
  "code": "date_past",
  "hint": "Pick a future time in the project's local time (see now in list_projects)."
}

Every error has a stable code (snake_case) to branch on, and some add links. Messages can change; codes don't.

{
  "error": "The user's Postika subscription is not active (canceled), so this connection can't read or schedule anything in the project \"Acme\". Tell the user to activate it at https://postika.app/billing; it works again right away, without reconnecting.",
  "code": "subscription_inactive",
  "billing_url": "https://postika.app/billing",
  "project_id": "3f6a1d2e-…",
  "subscription_status": "canceled"
}

Validation errors also list the fields that failed:

{
  "error": "Invalid data",
  "issues": [
    {
      "path": "when",
      "message": "Format \"YYYY-MM-DD HH:MM\""
    },
    {
      "path": "channel_ids",
      "message": "Too small: expected array to have >=1 items"
    }
  ]
}

Status codes#

Error messages#

OAuth errors#

The OAuth endpoints follow RFC 6749 and return { error, error_description }.

MCP errors#

Only authentication (401, with WWW-Authenticate) and rate limiting (429) are HTTP errors, as a JSON-RPC error with code -32001. Everything else, including an inactive subscription, is a tool result with isError: true and the text Error (<code>): <message>, so the AI can read it, tell the user what to do and correct itself. initialize and tools/list always succeed.

{
  "content": [
    {
      "type": "text",
      "text": "Error (too_long): X: maximum 280 characters (you have 312). Shorten the text, or create a separate post for this channel."
    }
  ],
  "isError": true
}

Rate limits#

120 requests per minute for each API key or OAuth access token, counted per clock minute (and 60 per IP for requests without a valid credential). REST and MCP requests share the same budget. Requests over the limit get 429 until the minute rolls over.

Every 429 response carries a Retry-After header with the seconds left until the next minute (1 to 60). Wait that long before retrying; the header is exposed to browsers through CORS.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{ "error": "Too many requests: wait a minute" }

Limits#

Network limits#

Checked when a post is scheduled, published or approved. The tightest channel in a post decides.