Error Codes

When a Blue GraphQL operation fails, the response contains a top-level errors array instead of (or alongside) data. Each entry carries a human-readable message and a machine-readable code at extensions.code. Switch on extensions.code in your client — never parse the message string, which is wording that can change.

Blue throws 147 intentional error codes from api/src/lib/errors.ts. They are listed in full below, grouped by area. Two codes are not in that file but you will still see them: BAD_USER_INPUT (input validation) and INTERNAL_SERVER_ERROR (the masked code applied to unexpected server failures — see Safe vs. masked errors).

Error response shape

{
  "errors": [
    {
      "message": "Todo was not found.",
      "path": ["updateTodo"],
      "extensions": {
        "code": "TODO_NOT_FOUND"
      }
    }
  ],
  "data": null
}

Each error object includes:

• message — a human-readable description. For display only; do not branch on it.
• extensions.code — the stable, machine-readable code. This is what you handle programmatically.
• path — the response path of the field that failed (e.g. the mutation name).
• extensions.data — present only on some codes; carries structured detail (see below).

A GraphQL response can succeed partially: data may hold results for the fields that resolved while errors describes the ones that didn’t. Always check errors even when data is non-null.

Structured error detail (extensions.data)

Some errors attach a structured payload so your client can react precisely instead of showing a generic toast.

BAD_USER_INPUT

Thrown for input that fails validation (Blue’s UserInputError). The validation detail is carried under extensions.data:

{
  "errors": [
    {
      "message": "Invalid input",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "data": { "field": "email", "reason": "must be a valid email address" }
      }
    }
  ]
}

The data shape varies by what was validated — treat it as an opaque object keyed by the offending input.

Name-formula validation is a specialization of this error. It arrives with extensions.code set to BAD_USER_INPUT like any other validation failure, and carries its own discriminator nested at extensions.data.code:

{
  "errors": [
    {
      "message": "Unknown field in formula.",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "data": { "code": "FORMULA_VALIDATION_ERROR" }
      }
    }
  ]
}

Branch on extensions.code first, then on extensions.data.code. FORMULA_VALIDATION_ERROR never appears as a top-level code.

PLAN_LIMIT_REACHED

This is the single signal for anything blocked by your plan or tier — over a resource cap, a feature your plan doesn’t include, a locked workspace, or a tier-level rate limit. There are no per-resource limit codes; route on the kind inside extensions:

{
  "errors": [
    {
      "message": "You've reached the workspace limit for your plan.",
      "extensions": {
        "code": "PLAN_LIMIT_REACHED",
        "kind": "over_limit",
        "resource": "workspaces",
        "current": 10,
        "limit": 10
      }
    }
  ]
}

Safe vs. masked errors

In production Blue runs every error through a formatter (api/src/lib/format-error.ts) before returning it. The rule is simple:

• An error is safe when the server intentionally threw a GraphQLError carrying an explicit code other than INTERNAL_SERVER_ERROR. Every code in this page’s tables is thrown that way, so its real message and code reach the client unchanged. There is no special-casing of *_NOT_FOUND — those are safe only because they’re thrown as coded GraphQLErrors, exactly like every other code here.
• An error is unsafe when it wasn’t thrown intentionally — an uncaught exception, or any error Apollo auto-wraps. The message is replaced with "Internal server error" and the code becomes INTERNAL_SERVER_ERROR (the original code is dropped). The full detail is logged server-side, never sent to the client.
• Prisma / database errors are a special unsafe case: the client receives the generic message "A database error occurred" with code INTERNAL_SERVER_ERROR.

{
  "errors": [
    {
      "message": "Internal server error",
      "extensions": { "code": "INTERNAL_SERVER_ERROR" }
    }
  ]
}

Treat INTERNAL_SERVER_ERROR as “retry or contact support” — it never carries actionable detail. In non-production environments the formatter is bypassed and the full original error (including stack traces) is returned for debugging.

Handling errors in your client

Switch on extensions.code, with a default branch for anything unrecognized:

const errors = response.errors ?? []

for (const err of errors) {
  switch (err.extensions?.code) {
    case 'UNAUTHENTICATED':
      // Token missing or invalid — re-authenticate.
      break
    case 'FORBIDDEN':
      // Authenticated, but the role can't perform this action.
      break
    case 'PLAN_LIMIT_REACHED':
      // Blocked by plan/tier — inspect extensions.kind and show an upgrade path.
      break
    case 'BAD_USER_INPUT':
      // Validation failed — read extensions.data for the offending field.
      break
    case 'RATE_LIMITED':
      // Back off and retry (see Rate Limits).
      break
    case 'TODO_NOT_FOUND':
      // The record doesn't exist or you can't access it.
      break
    default:
    // INTERNAL_SERVER_ERROR or any unhandled code — show a generic message and log it.
  }
}

Rate limiting

Most operations are governed by the per-tier rate-limit middleware documented on Rate Limits. A handful of sensitive or expensive operations have their own per-operation caps enforced by graphql-rate-limit (keyed by user, falling back to IP). Exceeding any of these returns the RATE_LIMITED code.

These per-operation limits sit on top of the tier limits — a request must pass both. See Rate Limits for the tier middleware and recommended backoff.

Error code reference

Every code below is thrown by the API. Messages are the exact strings the server returns (some are templated with context, indicated by …).

Authentication & access

Validation & input

Sign-in, sessions & invitations

Users & membership

Records, lists & dependencies

UNSUPPORTED_RECORD_QUERY comes from todos, records, recordQueries.todos, TodoList.todos and Tag.todos when the record engine cannot answer a filter or sort with the same rows the earlier engine returned. Blue refuses the request rather than drop the condition. The message ends with what to do: remove or change the named condition, or scope the query to one workspace with filter.projectIds. When the refused condition is your role’s record filter, ask a workspace administrator to change that filter. Shapes that return this code:

• a sort whose built-in field (title, due date, list) is missing on the workspace’s table;
• a fields[] condition that also matches empty values (NIN, NE, “is empty”) on a customFieldName that two or more live fields of one workspace share — address the field by customFieldId without customFieldName;
• a filter condition the record engine cannot evaluate (the reason names it);
• a role record filter the record engine cannot evaluate.

Ordering & concurrency

Records, lists and list items carry an explicit order. These codes report that a move could not be placed. Every code marked retryable below carries extensions.retryable: true — refetch the anchors, re-issue the same mutation, and it will normally succeed.

The two non-retryable codes mean different things: INVALID_PLACEMENT says the anchors you sent do not describe a valid position, so fix the request; ORDER_RANK_INVARIANT says the stored order is incomplete, which needs operator attention rather than a retry.

Workspaces, organizations & limits

Custom fields, tags & templates

Comments, activity & notifications

Checklists

Automations & webhooks

Dashboards & charts

Files, folders & documents

Forms

Imports

An import that would exceed your plan’s per-workspace record cap is rejected before it starts with PLAN_LIMIT_REACHED (resource: "records") — see that section above for the full error shape. There’s no import-specific limit code; the cap scales with your plan, same as everywhere else records are counted.

Custom domains & email

Billing & subscriptions

Community

System

Related

• Authentication — how to authenticate API requests
• Making Requests — request format, headers, and the GraphQL endpoint
• Rate Limits — per-tier limits and backoff guidance