Skip to Content
GrowSocialelion API

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, failed or not_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.
  • fix and correlationId: present when there is one thing to change, or when the failure is ours.

Status codes

HTTPcodeMeaning
400invalid_json, invalid_argumentsThe body is not a JSON object, or an argument does not fit the schema. The reason names the field. Nothing ran.
401unauthorizedNo key, or the key is unknown, expired or revoked.
403forbidden, scope, network, brandThe 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.
404unknown_endpoint, not_foundNo such endpoint, or the draft, series or run you named does not exist.
405method_not_allowedGET on an endpoint that takes POST only. Only free read-only endpoints take GET.
409refused, capped, failedA rule said no: a daily cap, the spend budget, credits, a duplicate draft, a series not approved yet. The reason says which.
422rejectedThe draft failed a voice or content check. Nothing was saved. The reason says what to change.
429rate_limitedOver the rate limit, or too many failed key attempts. Wait for the Retry-After header.
500internalSomething 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.