Errors
Every error has the same body: status, code and a reason you can act on.
Every error, from every endpoint, has the same JSON body. It is the same body an MCP client gets in structuredContent, so code that handles one handles both.
{
"status": "refused",
"code": "scope",
"reason": "This key does not hold the \"drafts\" scope that propose_post needs. Nothing was run.",
"fix": "Ask the workspace owner for a key with that scope."
}status:error,refused,rejected,capped,failedornot_found.code: a stable word to branch on.reason: one sentence a person can act on. It always says whether anything ran or was spent.fixandcorrelationId: present when there is one thing to change, or when the failure is ours.
Status codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_json, invalid_arguments | The body is not a JSON object, or an argument does not fit the schema. The reason names the field. Nothing ran. |
| 401 | unauthorized | No key, or the key is unknown, expired or revoked. |
| 403 | forbidden, scope, network, brand | The key may not do this: a missing scope, a network or brand the key is not bound to, or a browser Origin we do not allow. |
| 404 | unknown_endpoint, not_found | No such endpoint, or the draft, series or run you named does not exist. |
| 405 | method_not_allowed | GET on an endpoint that takes POST only. Only free read-only endpoints take GET. |
| 409 | refused, capped, failed | A rule said no: a daily cap, the spend budget, credits, a duplicate draft, a series not approved yet. The reason says which. |
| 422 | rejected | The draft failed a voice or content check. Nothing was saved. The reason says what to change. |
| 429 | rate_limited | Over the rate limit, or too many failed key attempts. Wait for the Retry-After header. |
| 500 | internal | Something broke on our side. Quote the correlationId to support. |
Retries
Retry 429 after Retry-After, and 500 once after a short wait. Do not retry 400, 403, 409 or 422 without a change: the same call gets the same answer.