Writing error messages for LLMs, not just humans

# Writing error messages for LLMs, not just humans Error messages are part of the API. For human-facing APIs, we've mostly figured this out: show a message the user can understand, maybe with a link to documentation. For LLM-facing APIs, the bar is different — and higher. An LLM that hits an error will include the error message in its reasoning about what to do next. A good error message gives the model enough information to recover. A bad error message leaves the model stuck, forcing it to either give up or try random things. We got this wrong in v0. Most errors were generic HTTP responses — "Not found", "Unauthorized", "Bad request". Useful for a developer reading logs. Useless for an LLM mid-conversation. ## The difference between human and LLM error messages **Human error message:** ```text Space not found. ``` A human reads this and knows to check the URL, maybe go back and look for the space again. **LLM error message:** ```text Space 'my-space' not found. Call mcp_list_spaces() to see all spaces you have access to, or check if the slug is spelled correctly. Note: personal space is accessed as 'personal', not '@personal'. ``` The LLM reads this and knows: 1. The specific slug that failed (`my-space`) 2. The exact tool to call next (`mcp_list_spaces()`) 3. A common mistake to check (the personal space slug format) One message is a description. The other is a recovery guide. ## Bindly's error response format Every MCP error response follows this structure: ```typescript return { content: [{ type: "text", text: formatError({ code: 'SPACE_NOT_FOUND', message: `Space '${slug}' not found.`, hint: `Call mcp_list_spaces() to see all accessible spaces, or verify the slug is correct.`, input: { slug } }) }], isError: true // tells the MCP client this is an error } ``` The rendered text: ```text [Error: SPACE_NOT_FOUND] Space 'my-space' not found. → Hint: Call mcp_list_spaces() to see all accessible spaces, or verify the slug is correct. → Input: { "slug": "my-space" } ``` Three components: a stable error code, a specific message with the failing value, and a hint with the next step. ## Recoverable vs unrecoverable errors The most important distinction in LLM error design: can the LLM recover within the current workflow, or does it need to stop and explain to the user? **Recoverable — the LLM should try something different:** ```text [Error: BINDING_NOT_FOUND] Binding 'my-binding' not found in space '@my-space'. → Hint: Call mcp_search({ query: "my-binding", spaceId: "<id>" }) to find bindings by content, or mcp_list_bindings({ spaceId: "<id>" }) to browse all bindings in this space. → Input: { "slug": "my-binding", "spaceId": "spc_abc" } ``` **Unrecoverable — the LLM should stop and inform the user:** ```text [Error: PERMISSION_DENIED] You don't have permission to edit binding 'some-binding' in space '@their-space'. → This binding was created by another member. Only admins and owners can edit it. Ask the space admin for elevated permissions, or work with the binding author directly. → Input: { "bindingId": "bnd_xyz", "action": "update" } ``` **Auth errors — requires user action, not LLM action:** ```text [Error: UNAUTHORIZED] Authentication required. Your session may have expired. → The user needs to reconnect Bindly. In Claude Desktop: Settings → Connections → Bindly → Reconnect. In Cursor: restart the app to re-authenticate. → If using a User Key, check that it hasn't been revoked at bind.ly/settings. ``` The hint for auth errors doesn't tell the LLM to call a tool — there's nothing the LLM can do programmatically. It tells the LLM to explain the problem to the user and exactly how to fix it. ## Including the failed input Every error response includes the input that caused the failure: ```text → Input: { "slug": "my-space", "action": "get" } ``` Two purposes: **Self-diagnosis**: The LLM can see exactly what it sent. If it sent `"my-space"` but should have sent `"@my-space"`, it can correct itself without asking the user anything. **User explanation**: When the LLM reports the error, it can say "I tried to access 'my-space' but it wasn't found" — specific, not vague. Without the input in the error, the LLM has to reconstruct what it tried from its own context, which may be stale if several tool calls have passed. ## Error codes as a stable contract Error codes (`SPACE_NOT_FOUND`, `PERMISSION_DENIED`, `BINDING_NOT_FOUND`) are part of the API contract. They should be: - **Stable** — don't rename them between versions - **Specific** — `BINDING_VERSION_NOT_FOUND` instead of `NOT_FOUND` - **Action-oriented** — the code should hint at what kind of problem it is A well-crafted system prompt can include: "If you receive BINDING_NOT_FOUND, search for it with `mcp_search` before giving up." This kind of error-handling logic only works if the error codes are predictable. If we rename `BINDING_NOT_FOUND` to `RESOURCE_MISSING`, those system prompts break silently. ## The 410 Gone pattern for share links Expired share links are a specific case where the error design matters for trust: ```text [Error: SHARE_EXPIRED] This share link expired on 2026-04-01. → The content it pointed to may still exist in the original space. Ask the link creator to generate a new share link, or request access to the space directly. → Share ID: b/abc123 ``` Compare to a generic 404: ```text Not found. ``` The 410 response tells the LLM (and the user) that this content *existed* but the link is no longer valid. Materially different from "this never existed." HTTP 410 Gone is the right status code precisely because of this distinction. ## Validation errors with field-level detail For creation and update operations, validation errors identify the specific field: ```text [Error: VALIDATION_FAILED] Request validation failed. → Fields: - title: Required. Must be 1-200 characters (got 0). - sourceType: Must be one of: url, text, file, conversation (got 'document'). → Fix these fields and retry. ``` More work to implement than a generic "invalid request" — it requires field-level validation with specific messages per field. But it's essential for LLM consumers. The LLM can read this and know exactly what to change in its retry. A generic "invalid request" leaves it guessing which field is wrong, often resulting in a cascade of failed retries burning context. ## What makes LLM error design hard The hardest part isn't the technical implementation — it's discipline. When building quickly, it's easy to write `return c.json({ error: 'Not found' }, 404)` and move on. The human-facing UI can add context. The documentation can explain the error codes. For LLM-facing APIs, the error message *is* the documentation, because the LLM reads it at the moment it's deciding what to do. There's no separate step where it looks up the error in a docs site. The useful question to ask when writing an error message: *"If this error appears in the middle of a multi-step workflow, what does the LLM need to know to continue — or to explain the failure to the user?"* That question usually points directly to the right message.