Error Codes

When something goes wrong, emend gives you an EmendAiError:

interface EmendAiError {
  readonly code: EmendErrorCode
  readonly message: string
  readonly retryable: boolean
}

code says what went wrong. Use it in your code, for example to show a different message for each error.
message is a ready-made message you can show to the user.
retryable is true if trying again might work. You still decide whether to show a Try again button.

All error codes

Code	Retryable	Default message
`invalid_protocol`	No	This request uses an unsupported emend protocol version.
`invalid_request`	No	The AI request is invalid.
`invalid_action`	No	That AI action is not available.
`invalid_instruction`	No	Add a valid instruction and try again.
`context_too_large`	No	The selected context is too large for this request.
`selection_required`	No	Select some text before using this action.
`pending_review`	No	Review or reject the pending document change first.
`request_in_progress`	No	Another AI request is already in progress.
`stale_revision`	No	The document changed while this request was open. Run the action again.
`aborted`	Yes	The AI request was cancelled.
`transport_error`	Yes	The AI service could not be reached.
`provider_error`	Yes	The configured AI provider returned an error.
`unauthorized`	No	This request is not authorized.
`rate_limited`	Yes	Too many requests. Try again shortly.
`markdown_unavailable`	No	This editor needs compatible Tiptap Markdown support.
`schema_unsupported`	No	The editor cannot safely accept this generated content.
`editor_not_configured`	No	This editor does not have emend AI configured.
`confirmation_required`	No	Confirm the document replacement before applying this proposal.
`apply_failed`	No	The proposal could not be applied safely.
`internal_error`	Yes	The request failed unexpectedly.

Where errors appear

useEditorAi().error: errors while sending the request or receiving the answer.
useEditorAi().reviewError: errors while previewing, accepting, or rejecting a suggestion.
createFetchTransport: passes on errors from the server, and turns HTTP statuses like 429 into error codes.
createEmendAiHandler: sends errors to the browser without exposing your server's internal details.

Create and check errors

import { createEmendError, isEmendErrorCode } from "@emend/ai"

const error = createEmendError("rate_limited")

if (isEmendErrorCode(error.code) && error.retryable) {
  // Offer a deliberate retry path.
}

createEmendError(code, message?) creates an error. You can pass your own message, but retryable always comes from the code. publicError(error, fallbackCode?) turns any thrown value into a safe error you can send to the browser.

What to do for each error

Error	What to do
Invalid request or setup	Fix the editor, action, instruction, or package setup.
`context_too_large`	Select less text, or let the AI read less, and try again.
`pending_review` or `request_in_progress`	Accept, reject, or stop the current request first.
`stale_revision`	Remove the old suggestion and run the action again.
Transport, provider, rate limit, or internal	Keep the user's text and offer a Try again button.
`unauthorized`	Ask the user to sign in again. Do not retry automatically.

See Troubleshooting and Limitations for common causes and fixes.

All error codes

Where errors appear

Create and check errors

What to do for each error

On this page