Adds docs for the AI features errors #309

Jordi-PV · 2024-06-27T15:26:08Z

Summary

This PR documents the errors that the Yoast AI features display.

Relevant technical choices

Technical choices that affect more than this issue:

None.

Test instructions

This PR can be acceptance tested by following these steps:

Open up https://document-ai-error-messages.yoast-developer.pages.dev/features/ai/ai-errors/
Read through and confirm everything is covered / readable.

Quality assurance

Security - I have thought about any security implications this code might add.
Performance - I have checked that this code doesn't impact performance (greatly).
Caching - I have analyzed the caching methods that this code touches and have added instructions to deal with those.
Tested - I have tested this code to the best of my abilities.
Automated tests - I have added unit tests to verify the code works as intended.
Testability - I have added unique ids to elements, so they can be located in automated testing.
I have altered a filename.
- I have adjusted the ID property accordingly and updated all internal links.
- I have added the redirect to the _redirects file in the root of the project.

cloudflare-workers-and-pages · 2024-06-27T15:32:45Z

Deploying yoast-developer with Cloudflare Pages

Latest commit:	`b76c57f`
Status:	✅ Deploy successful!
Preview URL:	https://108d0bcc.yoast-developer.pages.dev
Branch Preview URL:	https://document-ai-error-messages.yoast-developer.pages.dev

View logs

…ror-messages

mhkuu

Nice to see some documentation for this! 🎉 Here are some initial suggestions.

I would love to see more information on other possible errors:

site unreachable
inactive license
generic errors
... basically every error listed in assets/js/src/ai-generator/components/errors

docs/features/ai/ai-errors.md

sidebars.js

…ror-messages

Second pass on Yoast AI error descriptions.

marinakoleva · 2024-08-15T13:40:00Z

Swapped all mentions of "alert" or "alert modal" to "error message" (slack thread)
We could add slightly bigger images so that the error text is easier to read. I changed the first image as an example.
We could also add the text of the error to make it possible to copy it when needed, or to help with reading it. Again, an example was added to the first error.
Because the text of some error messages seems a bit unclear/ unhelpful, another task was created to improve them: Update copy and links of error messages
Crucially, I wonder whether this page is necessary to exist, given that we already have the page Common AI feature problems and errors on yoast.com. What we could do instead, is revamp the yoast.com page, and add the information and images on this page there.

marinakoleva · 2025-03-03T09:02:03Z

Whenever there are changes to the developer article in the future, Anne/ the person responsible for the Help centre should be informed so they can update the help article Common AI feature problems and errors.

marinakoleva · 2025-03-20T12:10:42Z

@mhkuu The plan is to have any relevant information that is mentioned in the article about Common AI feature problems and errors and is missing from the developer page added to the developer page.
Could you double check if the information in the yoast.com article is correct? Especially the following points:

The fact that the error "Something went wrong" (not sure if this refers to the WP request error or the generic error) could be caused by:
- site language and content language are different
- Site language is a formal language
- connection timeout -- is it possible to get this error instead of the Request timeout error?
Yoast AI cannot reach your site: the solutions mentioned

mhkuu · 2025-03-21T15:35:40Z

Everything regarding these errors/resolutions the help article is correct, except that the "something went wrong" error is not going to be shown on connection timeout, that line can be removed. You will see the connection timeout error instead.

…nt-AI-error-messages

JorPV · 2025-09-17T10:21:03Z

docs/features/ai/ai-errors.md

+### Rate limit error
+The use of Yoast AI comes with rate limits to ensure fair use. Moreover, we are in the process of introducing a subscription-based limit on the amount of AI generations per month. Please refer to [this page](https://yoa.st/ai-generator-rate-limit-help) to understand the rate limits that are applicable. 
+
+This error message is displayed when you surpass the Yoast AI rate limit for a specific time frame, or (in the future) your Yoast AI sparks limit.


Do we want to update this documentation once the AI features are tight to the use of sparks? Otherwise, maybe is better to remove the part within the parenthesis (in the future) ?

JorPV · 2025-09-17T11:23:33Z

docs/features/ai/ai-errors.md

+## Mocking these errors
+
+### In WordPress
+If you need to display these errors without actually triggering them (e.g., displaying the rate limit error without actually reaching the rate limit), you can do so by editing the function `get_suggestions` in `src/ai-generator/user-interface/get-suggestions-route.php` in the Yoast SEO repository. 


I would add the link to the repository https://github.com/Yoast/wordpress-seo

JorPV · 2025-09-17T11:34:27Z

docs/features/ai/ai-errors.md

+
+### In WordPress
+If you need to display these errors without actually triggering them (e.g., displaying the rate limit error without actually reaching the rate limit), you can do so by editing the function `get_suggestions` in `src/ai-generator/user-interface/get-suggestions-route.php` in the Yoast SEO repository. 
+Replace the content of the `throw` block with one of the errors below. Also, replace the variable in the following `catch` block with the name of the error (e.g. `Bad_Request_Exception`), and add the error to the imports (e.g. `use Yoast\WP\SEO\AI_HTTP_Request\Domain\Exceptions\Bad_Request_Exception;`).


I haven't been able to reproduce this steps 🤔 https://github.com/Yoast/wordpress-seo/blob/trunk/src/ai-generator/user-interface/get-suggestions-route.php

I don't see any throw block.

There are two catch blocks in the get_suggestions function. Because there is no throw block, it is unclear which catch should be edited.

JorPV

Great job @marinakoleva 👏🏼 I really like the tabs to display the errors information.

I've added some considerations to look at! 🙂

Adds docs for the AI features errors

3fe31a2

Jordi-PV marked this pull request as draft June 27, 2024 15:26

Jordi-PV added 2 commits June 28, 2024 10:22

Refines documentation

3e8bca3

Adjusts labels

ae9b1fb

Jordi-PV marked this pull request as ready for review June 28, 2024 08:35

Merge branch 'main' of github.com:Yoast/developer into document-AI-er…

3c87f11

…ror-messages

Jordi-PV marked this pull request as draft July 2, 2024 09:18

mhkuu suggested changes Jul 2, 2024

View reviewed changes

docs/features/ai/ai-errors.md Outdated Show resolved Hide resolved

docs/features/ai/ai-errors.md Outdated Show resolved Hide resolved

docs/features/ai/ai-errors.md Outdated Show resolved Hide resolved

sidebars.js Outdated Show resolved Hide resolved

Jordi-PV and others added 4 commits July 11, 2024 16:50

Merge branch 'main' of github.com:Yoast/developer into document-AI-er…

544d2e0

…ror-messages

Remove utm tags from the link

314c13d

Corrects spelling errors

fcd5b7e

Update ai-errors.md

17f4625

Second pass on Yoast AI error descriptions.

mhkuu approved these changes Jul 24, 2024

View reviewed changes

mhkuu added 3 commits July 24, 2024 11:50

Merge branch 'main' into document-AI-error-messages

4718c7a

Update ai-errors.md

e531224

Adds AI error images

1184a0b

mhkuu marked this pull request as ready for review July 24, 2024 11:56

Updates the images

0b30445

marinakoleva requested review from marinakoleva and removed request for marinakoleva August 1, 2024 06:36

marinakoleva self-assigned this Aug 1, 2024

edits the text

387fffe

marinakoleva added 3 commits March 3, 2025 10:40

merge main

77683b9

fixes merge conflict

09d5987

updates documentation with the newest versions of the error messages

4ab554c

marinakoleva added 2 commits September 10, 2025 16:46

Merge branch 'main' of https://github.com/Yoast/developer into docume…

c5a6e8e

…nt-AI-error-messages

updates info on how to mock AI errors

b76c57f

marinakoleva removed their assignment Sep 17, 2025

JorPV self-requested a review September 17, 2025 09:11

JorPV reviewed Sep 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Adds docs for the AI features errors #309

Adds docs for the AI features errors #309

Uh oh!

Jordi-PV commented Jun 27, 2024 •

edited by mhkuu

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Jun 27, 2024 •

edited

Loading

Uh oh!

mhkuu left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marinakoleva commented Aug 15, 2024

Uh oh!

marinakoleva commented Mar 3, 2025 •

edited

Loading

Uh oh!

marinakoleva commented Mar 20, 2025

Uh oh!

mhkuu commented Mar 21, 2025

Uh oh!

JorPV Sep 17, 2025 •

edited

Loading

Uh oh!

JorPV Sep 17, 2025

Uh oh!

JorPV Sep 17, 2025

Uh oh!

JorPV left a comment

Uh oh!

Uh oh!

Adds docs for the AI features errors #309

Are you sure you want to change the base?

Adds docs for the AI features errors #309

Uh oh!

Conversation

Jordi-PV commented Jun 27, 2024 • edited by mhkuu Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Relevant technical choices

Test instructions

Quality assurance

Uh oh!

cloudflare-workers-and-pages bot commented Jun 27, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying yoast-developer with Cloudflare Pages

Uh oh!

mhkuu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marinakoleva commented Aug 15, 2024

Uh oh!

marinakoleva commented Mar 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marinakoleva commented Mar 20, 2025

Uh oh!

mhkuu commented Mar 21, 2025

Uh oh!

JorPV Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JorPV Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

JorPV Sep 17, 2025

Choose a reason for hiding this comment

Uh oh!

JorPV left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Jordi-PV commented Jun 27, 2024 •

edited by mhkuu

Loading

cloudflare-workers-and-pages bot commented Jun 27, 2024 •

edited

Loading

marinakoleva commented Mar 3, 2025 •

edited

Loading

JorPV Sep 17, 2025 •

edited

Loading