Corrections to api-design/errors.mdx

api-design/errors.mdx

@@ -41,11 +41,11 @@ them effectively.
 
 HTTP status codes only set the scene for the category of issue that has
 occurred. An error like `400 Bad Request` is generally used as a vague catch-all
-error that covers a whole range of potential issues. 
+error that covers a whole range of potential issues.
 
 More information will be required to help developers understand what went wrong,
 and how to fix it, without having to dig through logs or contact the support
-team. 
+team.
 
 Error details are useful for:
 
@@ -173,7 +173,7 @@ up) but it _can_, and that covers the "link to documentation" requirement too.
 
 ![API Documentation for the SignatureAPI, with an explanation of what the error is, what happened, and how to fix it](./assets/errors-documentation.png)
 
-Why have both a `title` and a `description`? This allows the error to be used in
+Why have both a `title` and problem `detail`? This allows the error to be used in
 a web interface, where certain errors are caught and handled internally, but
 other errors are passed on to the user to help errors be considered as
 functionality instead of just "Something went wrong, erm, maybe try again or
@@ -200,6 +200,13 @@ Content-Type: application/problem+json
 
 This example shows the same `type`, `title`, and `detail`, but has extra bits.
 
+As per [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html), the
+`title` (such as `"Not enough credit."`) should be the same for all problems with the same `type`
+(`"https://example.com/probs/out-of-credit"` in this example),
+while the `detail` can include information that is specific to the
+current problem occurrence. In this case, the `detail` shows the
+the attempted debit amount `50` that exceeds the current balance `30`.
+
 The `instance` field allows the server to point to a specific resource (or endpoint)
 which the error is relating to. Again URI could resolve (it's a relative path to
 the API), or it could just be something that does not necessarily exist on the
@@ -239,7 +246,7 @@ Some folks want to consider HTTP as a "dumb pipe" that purely exists to move dat
 down, and part of that thinking suggests that so long as the HTTP API was able to respond then thats a 200 OK.
 
 This is fundamentally problematic, but the biggest issue is that it delegates
-all of the work of detecting success or failure to the client code. Caching tools will cache the error. Monitoring tools 
+all of the work of detecting success or failure to the client code. Caching tools will cache the error. Monitoring tools
 will not know there was a problem. Everything will look absolutely fine despite mystery weirdness happening throughout the system. Don't do this!
 
 ### Single or Multiple Errors?
@@ -291,7 +298,7 @@ where possible.
 
 When it comes to standards for error formats, there are two main contenders:
 
-**RFC 9457 - Problem Details for HTTP APIs**
+#### RFC 9457 - Problem Details for HTTP APIs
 
 The latest and greatest standard for HTTP error messages. There only reason not
 to use this standard is not knowing about it. It is technically new, released in
@@ -305,15 +312,15 @@ or other extensions.
 This helps avoid reinventing the wheel, and it's strongly recommended to use it
 if possible.
 
-**JSON:API Errors**
+#### JSON:API Errors
 
 [JSON:API](https://jsonapi.org/) is not so much a standard, but a popular
 specification used throughout the late 2010s. It focuses on providing a common
 response format for resources, collections, and relationships, but it also has a
 decent [error format](https://jsonapi.org/format/#errors) which a lot of people
 like to replicate even if they're not using the entire specification.
 
-**Pick One**
+#### Pick One
 
 There has been a long-standing stalemate scenario where people do not implement
 standard formats until they see buy-in from a majority of the API community, or
@@ -329,13 +336,13 @@ enough experience to avoid a lot of the common problems around.
 Smaller teams that are not in this privileged position can benefit from
 deferring to standards written by people who have more context on the task at
 hand. Companies the size of Facebook can roll their own error format and brute
-force their decisions into everyones lives with no pushback, but everyone on
+force their decisions into everyone's lives with no pushback, but everyone on
 smaller teams should stick to using simple standards like RFC 9457 to keep
 tooling interoperable and avoid reinventing the wheel.
 
 ### Retry-After
 
-API designers want their API to be as usable as possbile, so whenever it makes
+API designers want their API to be as usable as possible, so whenever it makes
 sense, let consumers know when and if they should come back and try again., and if so, when. The
 `Retry-After` header is a great way to do this.
 

claude.md

@@ -2,9 +2,9 @@
 
 ### **Markdown language**
 
-Speakeasy documentation and blog posts are written in [MDX](https://mdxjs.com/) (`.mdx` files). You may encounter some Markdown (`.md`) files.
+Speakeasy documentation and blog posts are written in [MDX](https://mdxjs.com/) (`.mdx` files). You may encounter some Markdown (`.md`) files.
 
-MDX (Markdown with JSX) uses the same formatting syntax for basic text elements as standard Markdown. This [guide to basic Markdown syntax](https://www.markdownguide.org/basic-syntax/) shows you how to format elements like headers, bold text, italic text, lists, and links.
+MDX (Markdown with JSX) uses the same formatting syntax for basic text elements as standard Markdown. This [guide to basic Markdown syntax](https://www.markdownguide.org/basic-syntax/) shows you how to format elements like headers, bold text, italic text, lists, and links.
 
 ### **Style specifics**
 
@@ -14,23 +14,23 @@ Speakeasy uses sentence case for titles and section headings globally.
 
 #### **Backticks**
 
-- In body text, place all references to code in backticks, including class names and `description` values.
+- In body text, place all references to code in backticks, including class names and `description` values.
 - Don’t use backticks in titles, headings, or subheadings because they don’t render well.
 - Don’t put language names in backticks unless it’s part of a code snippet:
-  - ❌ In `go`, all types from all operations are collected into a global `AcceptHeaderEnum` type.
-  - ✅ In Go, all types from all operations are collected into a global `AcceptHeaderEnum` type.
+  - ❌ In `go`, all types from all operations are collected into a global `AcceptHeaderEnum` type.
+  - ✅ In Go, all types from all operations are collected into a global `AcceptHeaderEnum` type.
 
 #### **Code blocks**
 
-Speakeasy documentation uses [Code Hike](https://codehike.org/) for code blocks.
+Speakeasy documentation uses [Code Hike](https://codehike.org/) for code blocks.
 
 - Prefer code blocks to inline code for code snippets.
 - Prefer YAML to JSON for code snippets where possible to improve readability. For example, use YAML for all OpenAPI document examples.
 - Try to add a language to all code blocks. This helps with syntax highlighting.
-- Use the `bash` language for shell commands.
-- Terminal output can be highlighted by copying the output with control sequences (copy using iTerm2), then pasting the output to a code block and selecting the `ansi` language. This will render the output with the correct colors and formatting.
-- The `ansi` language isn’t rendered as a Code Hike component. If you need to use the `ansi` language, use a standard code block.
-- The `mermaid` language is used for diagrams. This language is excluded from Code Hike rendering.
+- Use the `bash` language for shell commands.
+- Terminal output can be highlighted by copying the output with control sequences (copy using iTerm2), then pasting the output to a code block and selecting the `ansi` language. This will render the output with the correct colors and formatting.
+- The `ansi` language isn’t rendered as a Code Hike component. If you need to use the `ansi` language, use a standard code block.
+- The `mermaid` language is used for diagrams. This language is excluded from Code Hike rendering.
 
 #### **UI element labels**
 
@@ -141,21 +141,21 @@ Place inline code between backticks.
 
 Use backticks to reference bits of code you're narrating, but not for labels or button text.
 
-- ❌ Enter the filename and click `OK`.
-- ✅ Import the built-in node `http` package.
+- ❌ Enter the filename and click `OK`.
+- ✅ Import the built-in node `http` package.
 
 Avoid starting headings or sentences with backticks or code:
 
-- ❌ `request.args` is an ImmutableMultiDict.
-- ✅ The `request.args` attribute is an ImmutableMultiDict.
+- ❌ `request.args` is an ImmutableMultiDict.
+- ✅ The `request.args` attribute is an ImmutableMultiDict.
 
 ### Capitalization
 
 #### Titles and headings
 
 Capitalize titles and headings according to the customer's style guide if they have one or match capitalization to their existing documentation.
 
-At Speakeasy, we default to **sentence case** for titles and headings.
+At Speakeasy, we default to **sentence case** for titles and headings.
 
 - ✅ Using multiplayer with anonymous users
 
@@ -208,7 +208,7 @@ Correct comma splices by rewriting the independent clauses as complete sentences
 
 Alternatively, add a conjunction:
 
-- ✅ Download the files you need **and** unzip them on your computer.
+- ✅ Download the files you need **and** unzip them on your computer.
 
 Comma splices can be corrected by replacing the comma with a semicolon, but this approach is not recommended for our content:
 
@@ -237,17 +237,17 @@ Use decimal points when a number is not easily written out as a fraction: 1.273.
 
 ### Login, log in, log in to
 
-**login** (noun)
+**login** (noun)
 
 Your access credentials:
 
 - ✅ Keep your login details handy.
 
-**log in** (phrasal verb)
+**log in** (phrasal verb)
 
 - ✅ To make these changes, you'll need to log in.
 
-**log in to** The term "log in" is a phrasal verb, so we add the preposition after a space:
+**log in to** The term "log in" is a phrasal verb, so we add the preposition after a space:
 
 - ✅ Log in to GitHub.
 
@@ -299,18 +299,18 @@ Use double quotation marks to identify labels or button text:
 
 ### Setup vs set up
 
-We use **setup** as a noun or adjective:
+We use **setup** as a noun or adjective:
 
 - ✅ A microservices setup.
 - ✅ Follow the setup instructions.
 
-We use **set up** as a verb:
+We use **set up** as a verb:
 
 - ✅ How to set up your account.
 
 ### URLs and websites
 
-Avoid spelling out URLs, but when you need to, leave off `http://www.`.
+Avoid spelling out URLs, but when you need to, leave off `http://www.`.
 
 ### Word list