Error responses and error codes

When a FlowDrop API door refuses a request, it answers a JSON envelope carrying two things: a human-readable error and a machine-readable error_code.

{
  "success": false,
  "error": "The workflow changed on the server since it was loaded; reload before saving",
  "error_code": "CONFLICT"
}

Branch on the code, not the message

A client that classifies a refusal by matching substrings of error breaks silently the first time the wording changes — the match fails, the refusal is reclassified, and nothing errors. Compare error_code with === instead.

Adding a code is additive; renaming one is a break, and there is no deprecation path for a string clients compare exactly. A new condition gets a new code rather than widening an existing one.

A code names a condition, never a door or a route:

• It does not identify the resource — the route already does. NOT_FOUND on /workflows/{id} needs no WORKFLOW_NOT_FOUND spelling.
• It carries no field locator. That is what a 422's details[] is for.

Validation refusals carry details[]

A payload that decoded and then failed the rules answers 422 with VALIDATION_FAILED in the envelope and one entry per cause in details:

{
  "success": false,
  "error": "Workflow validation failed",
  "error_code": "VALIDATION_FAILED",
  "details": [
    {
      "code": "R14_EDGE_TYPE_UNKNOWN",
      "message": "Edge at position 2 declares edgeType \"loopbak\", which is not a recognised edge type. Use one of: data, trigger, tool_availability, loopback, agent_result.",
      "locator": "edge.2"
    }
  ]
}

The envelope code says which stage refused; details[].code says what about the payload was wrong. The two vocabularies are separate and spelled differently — the envelope uses screaming snake case, while details[].code carries whatever the rule that produced it publishes (R14_EDGE_TYPE_UNKNOWN from the workflow validator, version_mismatch from a stored-definition check, BUNDLE_FLOW_ID_INVALID from the bundle importer). Read details[].code to identify a cause; do not expect it to appear in the table below.

Thrown refusals use a different envelope

Some refusals never reach a controller at all — a permission denial, an unmatched path, a failed parameter conversion. Those are converted centrally, and the body they produce carries error, message and error_code:

{
  "error": "Access denied",
  "message": "The requested resource does not exist.",
  "error_code": "ACCESS_DENIED"
}

Here error is a generic label and message is the sentence worth reading. error_code means exactly what it means everywhere else, so a client that branches on it needs no special case.

When error_code is absent

The key is emitted only when a reason is known, and omission is deliberate — a fabricated code would be worse than none:

• A thrown 400 that names no reason. A 403 and a 404 mean one thing each and are mapped from the status alone. A 400 covers an empty body, an oversized body, undecodable JSON, a body that is not an object and a query parameter of the wrong type — five refusals with one status — so a 400 whose exception does not carry its own code carries no error_code. The refusals raised by the shared JSON decoder and the shared query-parameter reader do carry one, and every door that catches them relays it.
• Refusals the workflow and trigger doors throw rather than return. Those are still being migrated.
• The pipeline job door, which builds its own envelope and does not use the shared one.

Treat a missing error_code as "unclassified refusal" and fall back to the HTTP status — never to the message text.

The vocabulary

Next steps

• Edge structure — including the save-time validation code you will meet in details[].
• API reference — the endpoints themselves.