Errors, Retries and Abort in the SDK

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Retryable error

A failure that might succeed if tried again soon: statuses 408, 409, 429 and 5xx. The SDK sets isRetryable on them.

Backoff

Waiting longer before each retry, so a struggling service is not hit again at once.

RetryError

The SDK error (AI_RetryError) thrown when every retry failed. It holds errors and lastError.

Error chunk

A stream event {"type":"error","errorText":"…"} that reports a failure inside a 200 response.

Masking

Replacing a real error message with a safe one before it reaches the browser.

Reference id

A short id such as req-12 shown to the user and logged next to the real error, so support can find it.

friendly(error)

Your one function that turns any client error into a sentence for a person.

Partial message

An assistant message that holds only the text that arrived before a stop or a failure.

1. 1

   Retry once more than the failures

   In the first example change the first call's maxRetries: 2 to maxRetries: 1.

   The two failures need two retries, so the call now throws AI_RetryError: Failed after 2 attempts. Last error: …status 503 instead of recovering, and the example stops there with an uncaught error. Count your provider's typical hiccups before choosing the number.

2. 2

   Return the raw message

   In the third example change the server's onError to return error.message; and run it.

   The 'provider429' line now ends with the text from the provider, including the key fragment sk-live-DEMO. That is exactly the leak masking prevents.

3. 3

   Print error.message directly

   In the third example replace friendly(chat.error) in the last line with chat.error.message.

   The 401 and the own 429 now print raw JSON such as {"error":"signed_out"}, and the offline case prints Failed to fetch. That is what a person would see without a mapping function.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   The problem this solves: There are four places where an AI call can fail: before the request leaves (bad setup), at the provider (429, 5xx, 401), on the way (offline), and in the middle of a stream. Each reaches your code in a different shape, and a careless handler either shows the user a raw provider message (with account details in it) or hides everything behind 'Something went wrong'. This topic maps each shape to what you should do.

2. 2

   Retries in the SDK. generateText and streamText retry a call that fails with a retryable APICallError (status 408, 409, 429 or 5xx) up to maxRetries times, 2 by default, waiting longer each time and respecting a retry-after header. A non-retryable error such as a 401 is thrown at once, after one call. When retries run out you get an AI_RetryError (reason: "maxRetriesExceeded") with errors (every attempt) and lastError. The user waits through all of it, with the status stuck on submitted, so a high maxRetries makes the 'thinking' state long. Set it deliberately, and 0 when your own code does the retrying (Topic 1.4).

3. 3

   Two kinds of failure on the server. generateText throws, so you wrap it in try/catch. streamText does not throw: it returns at once, and a failure goes to the onError callback and into the stream as an error chunk (Topic 5.2). Reading result.text after a failed stream throws AI_NoOutputGeneratedError; result.textStream simply ends with nothing in it.

4. 4

   What the browser may read. By default the error chunk says only 'An error occurred.' To say more, return a string from onError in toUIMessageStreamResponse({ onError }). That string is what useChat puts in error.message. Use it to return a short, safe sentence and a reference id, and log the real error with the same id on the server. **Never return error.message as is**: provider messages can include key fragments, account ids, or prompt text.

5. 5

   Two shapes on the client. A failure inside the stream becomes the string you returned from onError (an Error whose message is that text). A failure *status* from your route (401, 429, 500, 502, 413) becomes an AI_APICallError whose statusCode is the status and whose message is the response body text, often JSON, sometimes an HTML error page from a proxy. Offline is a TypeError: Failed to fetch. Write one function friendly(error) that checks these three in order and returns a sentence; never print error.message directly. The client error does not carry the response headers, so if you want a countdown, put the seconds in the JSON body.

6. 6

   Abort and partial messages. stop() keeps what arrived. A broken stream keeps what arrived too, and moves to error. In both cases the partial text is in messages, with its text part in the streaming state. Mark such an answer in the UI ('Stopped' or 'Cut off') so nobody mistakes half a sentence for a finished one, and offer Continue or regenerate(). When you save chats, store the partial text with a flag (Topic 5.8).

• ↔

  Generous retries hide short outages but make users wait and add load to a provider that is already struggling. A low value shows errors sooner but needs a good retry button. Pick per feature.

• ↔

  Detailed error text helps users fix their own problems (for example 'message too long') but any detail from the provider can leak. Write your own messages for the cases you know and use a generic one plus a reference id for the rest.

• I can explain maxRetries, isRetryable and AI_RetryError.

• I can handle failures of generateText (catch) and streamText (onError and the stream).

• I can write an onError that returns a safe sentence and a reference id, and log the real error.

• I can write friendly(error) for stream errors, status errors and offline.

• I can keep a partial answer after a stop or a break and mark it as unfinished.