CTRLBOX / Error reference

IMPLEMENTATION GUIDE

Manual response guide

This site defines error contracts. Your application or automation constructs and sends the actual HTTP response.

Construct a response manually

  1. Select the definition that accurately describes the failure.
  2. Set the actual HTTP status to the definition’s status.
  3. Set Content-Type: application/problem+json.
  4. Copy the canonical type URI and stable title. Include a matching body status, safe occurrence-specific detail, and optionally an instance URI reference.
  5. Supply relevant HTTP headers. A 401 requires WWW-Authenticate; a 405 requires Allow. Respect each contract’s guidance on Retry-After.

Problem Details does not replace HTTP semantics. For example, a response to HEAD has no response body. Retry only when safe: a failed or timed-out write may already have taken effect.

Copyable n8n response example

Configure your Webhook node to respond using a Respond to Webhook node. In that node, choose Respond With: JSON, set Response Code: 422, and add the response header below. Paste the JSON body into Response Body. Node labels may vary by n8n version.

HTTP status: 422
Content-Type: application/problem+json
{
  "type": "https://errors.ctrlbox.dev/problems/validation-error",
  "title": "Validation failure",
  "status": 422,
  "detail": "One required field is missing.",
  "instance": "/occurrences/example-001",
  "errors": [
    {
      "pointer": "/customer/name",
      "message": "Provide a customer name."
    }
  ]
}

Replace example occurrence values with safe values from your workflow. Use the node’s status option to set HTTP status; the JSON status field alone does not set it. For another contract, also configure its required headers. No n8n integration or response handling is provided by this repository.

Stable type, individual occurrence

type is a URI reference identifying the problem type and is the primary identifier for machine consumers. This template uses absolute HTTPS URLs that resolve to human-readable definition pages. A response client should not automatically dereference arbitrary type URIs.

title is a short summary that SHOULD NOT vary between occurrences except for localization. detail explains this particular occurrence; consumers SHOULD NOT parse it for machine decisions. Use documented extensions for structured data. instance optionally identifies this particular occurrence and need not resolve to a page.

The body’s status is advisory. When present, generators MUST use the same status in the actual HTTP response. RFC 9457 defines five standard members: type, title, status, detail, and instance. It does not require all five. If type is omitted, it defaults to about:blank; this template explicitly supplies its own type URIs.

Extensions and safe disclosure

Custom extensions are scoped to a problem type. Consumers MUST ignore extensions they do not recognize. Do not reuse RFC member names. Publish the extension’s meaning and structure in the configuration.

Do not include credentials, personal information, stack traces, internal hostnames, or implementation diagnostics. Consider whether an occurrence URI or resource identifier discloses information. These examples use invented public identifiers.

Conventions and compatibility

The starter names, slugs, status mappings, and type URIs are template conventions, not an RFC-mandated catalogue. In particular, this template chooses 422 for syntactically valid content that fails validation; malformed syntax uses 400. Adapt your contracts to your API.

Keep established public type URIs stable, including domain and slug. Keep published definitions available. Create a new type for a substantially different meaning instead of repurposing an old URI. Changing the configured domain is suitable before publication; after publication, retain the old URLs and plan compatibility for existing clients.

Retry-After accepts an HTTP date or a nonnegative number of delay seconds. It is optional for 429 and 503; RFC 9110 says a temporary 413 condition SHOULD include it. It does not guarantee a later request will succeed.

Authoritative references