Errors

One error envelope, eight codes, and the request id to quote when you ask about one.

Updated 16 Sep 20262 min read

Every failure answers with the same envelope and the HTTP status that matches it. There is no second error shape anywhere in the API, so one handler covers every call you make.

{
  "error": {
    "code": "validation_failed",
    "message": "The request body does not match the schema for a kanban item.",
    "details": [
      {
        "path": "/data/columns/0/title",
        "message": "must be a string"
      }
    ],
    "docsUrl": "https://mockflow.com/developers/concepts/errors#validation_failed"
  },
  "requestId": "req_45d49816999bac40"
}

Fields

error.codeenum<string>required

A stable machine name. Switch on this, never on the message.

error.messagestringrequired

One sentence for a person, written to be shown to the caller. It can change between releases, so do not match on it.

error.detailsobject[]

Present on validation_failed. One entry per problem, each with the JSON path of the field that was refused.

error.docsUrlstring

The page explaining this code.

error.upgradeUrlstring

Present on plan_limit, where the fix is a plan rather than a payload.

requestIdstringrequired

Quote this when you ask us about a request. It is also returned on success, in the MockFlow-Request-Id header, and it is how we find the call in the log.

Codes

401unauthorized

No token, or a token that is expired, revoked or not a MockFlow token. Check the Authorization: Bearer header.

403forbidden

The token is good but is not allowed to do this: either the key lacks the scope the operation requires, or the account behind it cannot reach that board. The message says which.

404not_found

No such space, board, item, skill or job, or one the caller cannot see. The two are deliberately the same answer, so that probing ids tells you nothing.

422validation_failed

The body does not match the schema. details carries a JSON path per problem, so the field that is wrong can be pointed at rather than searched for.

409conflict

The request cannot apply to the current state: a member who is already a member, an Idempotency-Key reused with a different body.

402plan_limit

The workspace's plan does not allow this, such as one more board or an AI generation with no credits left. upgradeUrl goes to the plan page.

429rate_limited

Too many requests in the window. Retry-After says how many seconds to wait.

500internal

Our fault. Safe to retry with a delay. Quote the requestId if it persists.

Retrying

rate_limited and internal are worth retrying, with a delay that doubles each time. rate_limited says how long to wait in Retry-After. Nothing else is worth retrying: the same request will be refused the same way.

Retrying a write safely means sending an Idempotency-Key with the first attempt, not only with the retry.

Was this page helpful?