# Released Supply endpoint error matrix

[`endpoint-error-matrix.json`](endpoint-error-matrix.json) lists plausible HTTP `application/problem+json` `code`/status pairs for each method and path in [`openapi-v1.yaml`](openapi-v1.yaml). It is a scoped routing aid for partner client generation, QA, and review. It is not a claim that every runtime failure has been enumerated or that every listed branch has been exercised. The OpenAPI document is a branch preview, not evidence of production deployment or partner certification.

The matrix covers the released Phase 1 *contract catalog*: the exact method/path operations under `paths` in OpenAPI. It excludes branch-local reservation pull and acknowledgement routes (documented separately in the checkout-local/operator-only `reservation-preview-error-matrix.md`), admin Workbench errors, and asynchronous media `error_code` values returned inside successful resource envelopes. The broader [`error-registry.json`](error-registry.json) remains authoritative for globally valid HTTP code/status pairs and problem fields. A registry entry by itself does not mean that every endpoint can return it.

## Reading the JSON

Each `operations[]` row has an HTTP `method`, an OpenAPI relative `path`, names of inherited `shared` groups, and its own `errors` array. Every pair is `[code, HTTP status]`; expand the named groups and union them with `errors` to find an operation's plausible problem outcomes. `shared.authenticated` covers bearer authentication, connection/scope authorization, and Rack rate limiting. `shared.body_guard` covers size and media-type checks on every method, including body-bearing GET requests. `shared.body_write` adds malformed JSON for POST/PATCH. `shared.onboarding_idempotency` applies only to property create/connect/submit and unit/media create; its `resource_not_found` pair can arise when a prior successful response is replayed after its property mapping becomes invisible. `shared.resource_body` covers strict JSON object and field validation. These groups represent shared implementation paths, not guaranteed responses for every input.

For example, `GET /properties/{property_id}/ari` can return the authentication/rate-limit and body-guard pairs plus its row's missing property, unapproved property, invalid date, unknown unit, and readback size errors. `POST` to the same path has different codes and statuses, including `412 stale_revision`, `428 precondition_required`, and `422 unknown_unit`. Clients should key recovery on both `code` and HTTP status. Localized `detail` and `errors[].message` are display text.

## Evidence and maintenance

The row assignments come from `Api::V1::Supply::BaseController`, the resource controllers, `Supply::LocationDirectory`, property/unit field validators, `Supply::Ari::Readback`, `Supply::Ari::Validation`, `Supply::Ari::Apply`, and Rack Attack's Supply throttle. The focused contract spec requires one matrix row per released OpenAPI method/path, registered code/status pairs, and a declared Problem response for each status. A request-spec hook checks the **final observed problem response of each example** against the matching released or separate reservation-preview matrix. It does not prove unexercised branches; add targeted request examples when changing a behavior.

When changing a released endpoint, update the source, registry, OpenAPI response status, matrix row, and relevant request examples together. Keep operation-specific pairs on the operation row. Add a shared group only when the same path genuinely applies to all operations that inherit it. Do not infer endpoint coverage from every code in the global registry.

## Known limits

The global payload and media-type guards run on GET as well as write methods, so a body-bearing GET can produce `413 payload_too_large` or `415 unsupported_media_type`. These pairs are included in `body_guard`; generated clients should still issue GET requests without bodies. This matrix excludes framework-generated, infrastructure, and unhandled 5xx responses. The request-spec hook sees the last response in each RSpec example, so an intermediate error in a multi-request example is not checked by that hook.