[jayfeng7]

What

• Step 5 (Handle Errors): drop the nonexistent TooManyRequestsError import and the this.getRetryAfter(error) call, throw APICallError for the failed response, and fill in the required message / url / requestBodyValues fields so the sample type-checks. The explicit isRetryable override is removed so APICallError's default retryable behavior (408/409/429/5xx) applies.
• Step 6 (Workflow serialization): replace the nonexistent serializeModel / deserializeModel helpers with serializeModelOptions plus a hand-written [WORKFLOW_DESERIALIZE], matching how provider packages actually implement workflow serialization (e.g. packages/deepinfra/src/deepinfra-chat-language-model.ts, packages/provider-utils/src/evaluation-language-model.ts).

Why

• TooManyRequestsError, serializeModel, deserializeModel, and getRetryAfter do not exist anywhere in the packages, so readers copying the tutorial hit import errors and type errors.
• The original sample's explicit isRetryable: status >= 500 && status < 600 excludes 429 from retryability, which contradicts APICallError's documented default (packages/provider/src/errors/api-call-error.ts treats 408/409/429/5xx as retryable).

How checked

• Grepped all packages/* for TooManyRequestsError, serializeModel, deserializeModel: zero matches; serializeModelOptions, WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE are exported from @ai-sdk/provider-utils (packages/provider-utils/src/index.ts).
• The replacement serialize/deserialize bodies mirror the canonical in-repo usage verbatim (deepinfra chat model).
• Also searched open PRs for existing work on these names before opening.

[jayfeng7]

Friendly ping — same situation as #21996: docs-only fix removing references to error/serialization APIs that don't exist in the current SDK. Bot checks are green and CI is pending approval; an approval whenever convenient would be much appreciated.

[gr2m]

Still relevant, but the remaining issue below prevents a confident merge.

[gr2m]

[P2] Keep deserialized headers compatible with the model config. serializeModelOptions resolves a function-valued headers property and serializes the returned object. After this new deserializer restores that config, the following this.config.headers?.() example calls a plain object and throws TypeError. Update the header config/access pattern to support resolved headers, and correct the accompanying claims that headers are omitted.

[jayfeng7]

Fixed in 136ef31.

You are right, and the old shape was worse than a doc typo: it typechecked. Under headers?: () => Record<string, string | undefined>, this.config.headers?.() produces zero tsc errors while throwing at runtime on the model the deserializer restores — I reproduced both halves against the real signatures:

old config type + `headers?.()`   -> tsc: 0 errors
deserialized config               -> TypeError: this.config.headers is not a function

Three changes, all in this page:

Config type accepts what the deserializer restores.

import type { Resolvable } from '@ai-sdk/provider-utils';

type CustomChatConfig = {
  provider: string;
  baseURL: string;
  headers?: Resolvable<Record<string, string | undefined>>;
  fetch?: FetchFunction;
  generateId?: () => string;
};

Both request paths resolve instead of call. The postJsonToApi call in doGenerate and the fetch call in doStream use

this.config.headers ? await resolve(this.config.headers) : undefined

wrapped in combineHeaders(..., options.headers). The ternary is not defensive noise: headers is optional and resolve() does not accept undefined, so without it the fixed snippet does not compile. This is the same shape amazon-bedrock and anthropic already use, and Resolvable is the type their configs declare.

The claims are corrected. headers is no longer described as filtered out — it is the one special case, resolved during serialization and kept, and only fetch/generateId are dropped. The note no longer says a deserialized model has no auth headers (it does); it now says the resolved map travels with the payload, which is the consequence a reader actually needs to know about, and points at options.headers if a key must not be serialized.

Reading serializeModelOptions to make sure the page matches it: resolveSync calls a function-valued headers and throws SerializationError on a promise, then the resolved object is kept only when isJSONSerializable accepts it. Both facts are stated on the page now, because a page that says headers are omitted makes the sync requirement invisible.

I also replaced the combineHeaders Before/After with the resolved form, so the "after" is copy-pasteable rather than a sketch. If you would rather the page keep the un-combined this.config.headers() from Step 2 and only show resolve there, say so — I kept combineHeaders because that is what the request-level options.headers merge needs and it was already in the snippet you reviewed.

[jayfeng7]

Thanks for the thorough review — this is addressed in the current head. Commit 136ef31 ("docs(custom providers): keep deserialized headers compatible with the config") replaces this.config.headers?.() with await resolve(this.config.headers) from @ai-sdk/provider-utils at both call sites (doGenerate and doStream), and adds a Note explaining why optional chaining is not a safe substitute.

The Resolvable<...> type is also introduced in the config so deserialized models carry the resolved header map, and the docs now state that the function must be synchronous (async headers throws SerializationError).

The diff between your reviewed head (e22e8929) and the current head (30d2c0f6) is: git diff e22e8929..30d2c0f6 -- content/providers/05-community-providers/01-custom-providers.mdx — the resolve pattern and the Note block are the only new changes to this file.

[jayfeng7]

The [P2] fix is in 136ef31, plus one formatting follow-up in a0d924d.

One thing about the red Lint & Format check, so it is not read as fallout from this PR: it fails on three files this PR does not touch, and it fails on main too.

main @ a1db2092  Lint & Format  failure
  content/docs/03-ai-sdk-core/41-skill-uploads.mdx
  content/docs/06-advanced/01-prompt-engineering.mdx
  content/docs/07-reference/01-ai-sdk-core/14-upload-skill.mdx
  Format issues found in above 3 files.

That list comes from the job log of main's own run, not from this PR's. This page is clean under the repo's pinned oxfmt@0.41.0 on an LF checkout:

$ oxfmt --check content/providers/05-community-providers/01-custom-providers.mdx
All matched files use the correct format.

while the same command flags exactly those three files at a1db2092, so the regression came in with the docs sweep on main. I did introduce one issue of my own here — a two-paragraph <Note> whose second paragraph was indented, which oxfmt de-indents — and fixed it in a0d924d. I left the other three alone rather than widen a docs-accuracy PR; say the word and I will send them as a separate PR.

[jayfeng7]

Following up on my earlier note about the red Lint & Format check, since I now have the full picture rather than a guess.

The current head (a0d924d) fails on exactly three files, and 01-custom-providers.mdx is not one of them:

content/docs/03-ai-sdk-core/41-skill-uploads.mdx (49ms)
content/docs/06-advanced/01-prompt-engineering.mdx (31ms)
content/docs/07-reference/01-ai-sdk-core/14-upload-skill.mdx (14ms)

Format issues found in above 3 files.

All three are unformatted on main itself at a1db2092, which is why every pull request inherits the failure — the job checks the merge with main, not just the diff. I reproduced it on an LF checkout with the pinned oxfmt@0.41.0: those three files report format issues at a1db2092, and oxfmt --check over the whole tree is clean once they are formatted.

So rather than keep asking for an exception, I opened #23601, which applies oxfmt to exactly those three files and nothing else. If it lands, this PR's check should go green on the next run without any further change here — the remaining red is entirely upstream.

The one format issue that was mine — a two-paragraph <Note> whose second paragraph was indented — is fixed in a0d924d, and this page is clean under oxfmt@0.41.0 on an LF checkout.

[jayfeng7]

Merged main into the branch (a0d924d → 30d2c0f6) to clear the last red check.

Lint & Format was failing on three files this PR does not touch (41-skill-uploads.mdx, 01-prompt-engineering.mdx, 14-upload-skill.mdx). Main has since fixed them in #23609 (f2876d0b48), so the merge carries the fix in: Lint & Format now passes on the new head and the diff is still just the one custom-providers page. Nothing else changed — remaining checks are still running, and the PR is down to your re-review.

[jayfeng7]

@gr2m — the P2 you flagged (deserialized headers calling this.config.headers?.() on a plain object) is addressed in the current head.

What changed since your review (commit 136ef319, pushed 49 minutes after your review landed):

1. this.config.headers?.() is replaced with await resolve(this.config.headers) from @ai-sdk/provider-utils at both call sites (doGenerate and doStream) — resolve() passes a plain object through and calls a function, so a deserialized model with a resolved header map works correctly.
2. The config type now uses Resolvable<Record<string, string | undefined>> from @ai-sdk/provider-utils, matching the pattern used by the AI SDK's own providers.
3. The accompanying claims that headers are "not serialized" are corrected: serializeModelOptions resolves a function-valued headers and keeps the returned object, so a deserialized model carries its header map.
4. A Note block is added explaining why optional chaining is not a safe substitute.

Diff since your review: git diff e22e8929..30d2c0f6 -- content/providers/05-community-providers/01-custom-providers.mdx

Could you re-review when you have a moment? The changes are confined to this one file.

[jayfeng7]

@gr2m — the P2 you flagged (deserialized headers calling this.config.headers?.() on a plain object) is addressed in the current head.

What changed since your review (commit 136ef319, pushed 49 minutes after your review landed):

1. this.config.headers?.() is replaced with await resolve(this.config.headers) from @ai-sdk/provider-utils at both call sites (doGenerate and doStream) — resolve() passes a plain object through and calls a function, so a deserialized model with a resolved header map works correctly.
2. The config type now uses Resolvable<Record<string, string | undefined>> from @ai-sdk/provider-utils, matching the pattern used by the AI SDK's own providers.
3. The accompanying claims that headers are "not serialized" are corrected: serializeModelOptions resolves a function-valued headers and keeps the returned object, so a deserialized model carries its header map.
4. A Note block is added explaining why optional chaining is not a safe substitute.

Diff since your review: git diff e22e8929..30d2c0f6 -- content/providers/05-community-providers/01-custom-providers.mdx

Could you re-review when you have a moment? The changes are confined to this one file.