Skip to content

README.md

Latest commit

 

History

History
63 lines (45 loc) · 2.57 KB

README.md

File metadata and controls

63 lines (45 loc) · 2.57 KB

TKS API Problem Types

This directory contains human-readable documentation for every problem type the TKS API may return in an application/problem+json response body (RFC 9457 Problem Details for HTTP APIs).

These markdown files are synced to the public cloud104/tks-api-docs repo by CI on merge to main, where they're served as the help_url field on problem responses.

Problem type identifiers

TKS API uses RFC 4151 tag URIs for problem type identifiers:

tag:tks.sh,2026:tks-api/<category>/<slug>
  • tks.sh — the domain TKS owns (authority)
  • 2026 — the year this URI scheme was minted (fixed forever for this namespace)
  • tks-api/<category>/<slug> — path-like specific part

Tag URIs are non-resolvable by design. They're stable identifiers that clients match as strings. The dereferenceable help_url pointer (populated at runtime by the server from the TKS_DOCS_BASE_URL config) carries the link to the corresponding markdown file in this folder.

Categories

http/

Protocol/transport level errors — bad requests, auth failures, not found, timeouts, generic 5xx. These map to RFC 9110 HTTP status codes and are typically raised in middleware, handlers, or generic error paths.

domain/

Business rules, validation, and service-layer errors. These are specific to TKS domain logic — provider constraints, last-owner guards, insufficient role checks, duplicate resources, optimistic lock conflicts.

Adding a new problem type

  1. Add the URI constant to internal/problems/types.go
  2. Register it in internal/errregistry/init.go with a typed error and any extension fields the problem should include
  3. Add the corresponding markdown file in docs/problems/<category>/<slug>.md
  4. Update openapi/components/schemas/KnownProblemType.yaml — add the new tag URI to the enum and a matching x-enum-varnames entry
  5. Run make generate to regenerate OpenAPI code + SDK
  6. Merge — CI will sync the markdown to cloud104/tks-api-docs

For client developers

When handling a problem response:

  1. Match on type as the primary identifier. Treat it as an opaque string — don't parse the tag URI structure.
  2. Use help_url to link users to documentation. Don't auto-follow it in code (RFC 9457 §3.1.1 forbids this); only present it to humans.
  3. Read extension fields (under extensions or as sibling fields) for structured error data specific to each problem type. See each type's markdown file for the contract.