Error Codes

Error Codes documents your API’s own application-level error codes, the kind that ride inside a response body rather than the HTTP status line itself, such as an invalid_request_error type with an parameter_missing code. It’s the companion to Status Codes, which covers plain HTTP status codes like 404 or 500. Use Status Codes for the transport layer and Error Codes for whatever error shape your API returns on top of it.

Adding the block#

1. In the block editor, open the block inserter and search for Error Codes.
2. Add it to the page, usually on a shared errors reference page.
3. Give the table a title, e.g. Error Codes, and optionally an intro line explaining the shared error shape.
4. Click + Add error for each error type and code you want to document.

Settings#

Per row:

Example#

One row: Error type invalid_request_error, Error code parameter_missing, Description A required parameter was not provided.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: email.",
    "param": "email"
  }
}

The block#

In the editor, this is one error row filled in as above, no shortcode needed.

The shortcode#

The same block, added as a shortcode instead, for a widget, classic-editor content, or a page builder that only accepts shortcodes. Since errors is a JSON array, it can never go in a quoted attribute (a JSON array always contains a ], and the shortcode parser stops at the first literal ] it finds, quoted or not). It goes between the opening and closing tags instead:

[nahnu_code_block block="error-codes" title="Error Codes"]
[{"type":"invalid_request_error","code":"parameter_missing","description":"A required parameter was not provided."}]
[/nahnu_code_block]

Putting the JSON between the tags, rather than in a quoted attribute, is what keeps the shortcode from cutting off partway through.

How it renders#

A table titled “Error Codes” with one row: invalid_request_error, parameter_missing, and the description text.

Tips#

• Keep error type and error code naming consistent across the whole table. If your API always returns type and code in the same shape, say so once in the intro text instead of repeating it in every description.
• Group related errors together, e.g. all invalid_request_error rows before all authentication_error rows.
• Add an example error body for anything non-obvious. A reader parsing errors programmatically needs the exact shape, not just a description.