Error Codes

Why this stays simple on purpose

The API deliberately doesn't invent a large proprietary error-code taxonomy — it reports errors the way a well-behaved REST API already should: a standard HTTP status code you can branch on immediately, plus a JSON body for the human-readable detail. If you've integrated against any conventional REST API before, there's nothing new to learn here.

Error response shape

Every failed request returns a standard HTTP status code and a JSON body with a human-readable message:

HTTP/1.1 403 Forbidden
{
  "error": "Forbidden"
}

In most cases, the status code alone is enough to branch your logic — use it the same way you would for any REST API:

• • 400 — invalid request (missing or malformed body/JSON)
• • 401 — no valid session
• • 403 — authenticated, but not allowed to perform this action
• • 404 — resource doesn't exist, or you don't have access to it
• • 422 — validation failed (see the response body for details)

Machine-readable codes

A handful of endpoints add a stable code field you can match on, for cases where the status code alone isn't specific enough to know what to do next:

• • NO_ACCOUNT — returned by workspace invites when the invited email has no Fimaflow account yet.

Everywhere else, treat the error field as a message meant for display, not for branching logic on.

Validation errors

A 422 response from an endpoint backed by a schema includes the field-level details from that schema, so you can surface exactly what was wrong instead of a generic message.

Handling errors in your integration

Branch on the status code first, and only inspect the body when you need the detail — this keeps your error handling correct even for endpoints that later add a more specific code or extra fields, since you're not depending on their exact shape to know a request failed:

const res = await fetch("/api/workflows/wf_123/run", { method: "POST" });

if (!res.ok) {
  const body = await res.json();
  if (res.status === 422) {
    // body.errors has field-level detail — see "Validation errors" below
  }
  throw new Error(body.error ?? `Request failed with ${res.status}`);
}

Interactions with the rest of the platform

• • A node failure inside a workflow run (a failed SQL query, an unavailable AI provider) is a separate concept from an API error — it's reported in the execution log, not as an HTTP status on the triggering request. See Debugging for how node-level failures surface.
• • Auth-related 401/403 responses from an endpoint protected by an Auth node come from that node's invalid output, not from a separate platform-level gate.