Skip to content

Simplify supplementary error documentation - #126

Open
YadingFang wants to merge 1 commit into
mainfrom
docs/simplify-error-documentation
Open

YadingFang wants to merge 1 commit into
mainfrom
docs/simplify-error-documentation

Conversation

@YadingFang

@YadingFang YadingFang commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

What type of PR is this?

documentation

What this PR does / why we need it:

Addresses the documentation consistency finding recorded in #124 after the r2.2 release review.

The supplementary API documentation currently maintains its own list of 422 business error codes in addition to the OpenAPI definition. This duplicated error catalogue can become out of sync when the API definition evolves, as happened when EVENT_NOTIFICATIONS_NOT_SUPPORTED was added for Commonalities r4.4 alignment.

This PR simplifies the supplementary documentation so that the OpenAPI definition remains the authoritative source for operation-specific HTTP status codes and CAMARA error codes.

The changes:

  • remove the duplicated 422 business error-code catalogue from documentation/API_documentation/click-to-dial_API.md
  • retain a short explanation of the standard CAMARA ErrorInfo structure and a generic error-response example
  • explicitly refer readers to the OpenAPI definition for the authoritative set of HTTP status codes and error codes
  • replace the fixed status-code summary in the Quick Start section with a reference to the OpenAPI definition
  • keep business-flow-specific error explanations where they help users understand API behavior

No API definition or test behavior is changed by this PR.

Which issue(s) this PR fixes:

Fixes #124

Special notes for reviewers:

This is intentionally a documentation-only change.

The goal is not only to add the missing EVENT_NOTIFICATIONS_NOT_SUPPORTED entry, but to avoid future inconsistencies by removing the duplicated error-code catalogue from the supplementary documentation.

The OpenAPI definition remains the normative source for the errors applicable to each operation.

@camara-validation

Copy link
Copy Markdown

CAMARA Validation — PASS

0 errors, 0 warnings, 0 hints | Profile: standard

View full results

@YadingFang
YadingFang marked this pull request as ready for review September 15, 2026 03:35
@YadingFang

Copy link
Copy Markdown
Contributor Author

@tanjadegroot I addressed #124 by removing the duplicated 422 error-code catalogue from the supplementary API documentation and keeping the OpenAPI definition as the authoritative source for operation-specific status and error codes.

This follows the second option suggested in the issue and should help avoid similar documentation drift in future releases. Could you please take a look?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Release r2.2 review findings

1 participant