Errors

REST errors always come as { "ok": false, "error": { "code", "message" } }. On MCP, problems an app can fix come back as tool results with isError: true.

Code	HTTP	Meaning
`invalid_request`	400	The request is malformed or missing a required field. The message says what to fix.
`tool_error`	400	The action ran but could not do what was asked, for example a draft that does not exist. The message says why.
`unauthorized`	401	No key, or the key is not valid or was revoked.
`insufficient_credits`	402	The action needs more AI credits than the account has. Nothing ran.
`forbidden`	403	Your plan or the key's level does not allow this.
`not_found`	404	There is no such action.
`method_not_allowed`	405	Actions are called with POST.
`conflict`	409	The Idempotency-Key was used for a different request, or that request is still running.
`rate_limited`	429	Too many requests this minute. Retry after Retry-After seconds.
`limit_reached`	429	A daily limit is used up. The error says when it resets (00:00 UTC).
`internal_error`	500	Something went wrong on Chirpy's side. It is safe to retry, best with an Idempotency-Key.