chore: streamline error code over oas

[wim07101993]

Summary

Some places used generated error codes, other specified them directly. This pr aims to stream line that by only using the generated codes.

Validation

• go generate ./...
• go test ./...
• go test -tags postgres_integration ./...
• go test -tags spanner_integration ./...

Release notes / changeset

• Changeset: .changeset/error-codes-in-oas.md — streamline error code in oas (list @zitadel/server for server changes)

Notes

• I (Claude) had to change the error code generator.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nextgen	Ready	Preview	Aug 7, 2026 12:47pm
nextgen-docs	Ready	Preview	Aug 7, 2026 12:47pm
nextgen-mock-zitadel	Ready	Preview	Aug 7, 2026 12:47pm

[github-actions]

🦋 Changeset detected

Latest commit: 15ed3a2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 20 packages

Name	Type
@zitadel/server	Minor
@zitadel/api	Minor
@zitadel/cli	Minor
@zitadel/components	Minor
@zitadel/config	Minor
@zitadel/sdk-angular	Minor
@zitadel/sdk-core	Minor
@zitadel/sdk-next	Minor
@zitadel/sdk-nuxt	Minor
@zitadel/sdk-qwik	Minor
@zitadel/sdk-react	Minor
@zitadel/sdk-solid	Minor
@zitadel/sdk-svelte	Minor
@zitadel/sdk-vue	Minor
@zitadel/testing	Minor
@zitadel/server-linux-x64	Minor
@zitadel/server-linux-arm64	Minor
@zitadel/server-darwin-x64	Minor
@zitadel/server-darwin-arm64	Minor
@zitadel/server-win32-x64	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

This PR standardizes OpenAPI “default” error responses to be operation-specific (typed) and generated from the actual Go implementation’s reachable domain.Err* constructors, reducing drift between code, spec, and generated clients.

Changes:

• Add a Go static analysis package (api/internal/erroranalysis) to infer per-service-method domain error sets from implementation code paths.
• Update OpenAPI endpoint specs to $ref generated, operation-specific error response schemas (and add the generated files).
• Refactor server handler/service wiring (notably UserService) and handler error returns to support analysis + typed error models in generated code.

Reviewed changes

Copilot reviewed 73 out of 77 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/service/user.go	Introduces UserService interface and unexports concrete implementation for analysis/mocking/wiring.
internal/service/flow_create_user_with_password_handler.go	Switches handler dependency from concrete UserService internals to an injected DB pool for ID minting.
internal/service/flow_create_user_with_password_handler_test.go	Updates fixture to pass the new DB dependency.
internal/service/flow_create_user_for_passkey_handler.go	Uses UserService interface instead of concrete pointer.
internal/service/auth_attempt.go	Updates documented error lists to align with current auth-attempt semantics.
internal/api/project.go	Returns errors directly (for centralized encoding) instead of building response wrappers inline.
internal/api/integration_test/helpers/user.go	Updates helper return type to the service.UserService interface.
internal/api/integration_test/helpers/harness.go	Updates cached dependency type for UserService.
internal/api/integration_test/helpers/flow.go	Passes service DB dependency into create-user flow handler helper.
internal/api/handler.go	Switches handler field/constructor to accept service.UserService interface.
internal/api/flow.go	Normalizes flow errors before returning so encoded errors preserve sentinel messages/codes.
internal/api/flow_error_test.go	Updates tests to assert via normalizeFlowError + errorResponse pairing.
go.mod	Promotes golang.org/x/tools to a direct dependency (needed for go/packages).
cmd/server/server.go	Wires service DB pool into flow create-user handler constructor.
api/openapi/endpoints/users/methods.yaml	Replaces inline default error response with generated $ref files.
api/openapi/endpoints/users/me/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/users/me/getMyUser-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/users/listUsers-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/users/createUser-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/users/by_id/teams/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/users/by_id/teams/listUserTeams-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/users/by_id/password/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/users/by_id/password/setUserPassword-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/users/by_id/passkeys/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/users/by_id/passkeys/listUserPasskeys-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/users/by_id/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/users/by_id/GetUserByID-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/users/by_id/DeleteUserByID-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/sessions/query/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/sessions/query/querySessions-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/sessions/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/sessions/createSession-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/sessions/me/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/sessions/me/revokeMySession-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/sessions/me/getMySession-error-response.yaml	Normalizes quoting/order in schema examples and discriminator mapping.
api/openapi/endpoints/sessions/exchange/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/sessions/exchange/exchangeHandoff-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/sessions/by_id/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/sessions/by_id/getSession-error-response.yaml	Normalizes quoting/order in schema examples and discriminator mapping.
api/openapi/endpoints/sessions/by_id/revokeSession-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/projects/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/projects/createProject-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/projects/query/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/projects/query/queryProjects-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/projects/by_id/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/projects/by_id/getProject-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/projects/by_id/patchProject-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/flow/createFlow-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow/submit/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/flow/submit/submitFlowStep-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow/session/methods.yaml	Replaces inline default error response with generated $ref.
api/openapi/endpoints/flow/session/getFlowStep-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow_definitions/methods.yaml	Replaces inline default error response with generated $ref files.
api/openapi/endpoints/flow_definitions/createFlowDefinition-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow_definitions/listFlowDefinitions-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow_definitions/by_id/methods.yaml	Replaces inline default error response with generated $ref files.
api/openapi/endpoints/flow_definitions/by_id/getFlowDefinition-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow_definitions/by_id/updateFlowDefinition-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/flow_definitions/by_id/deleteFlowDefinition-error-response.yaml	Adds generated, operation-specific error response schema.
api/openapi/endpoints/auth_attempts/createAuthAttempt-error-response.yaml	Normalizes YAML scalar quoting in examples.
api/openapi/endpoints/auth_attempts/by_id/getAuthAttempt-error-response.yaml	Normalizes YAML scalar quoting in examples.
api/openapi/endpoints/auth_attempts/by_id/handoff/createHandoff-error-response.yaml	Updates schema to include already-handed-off + normalizes quoting.
api/openapi/endpoints/auth_attempts/by_id/challenges/issueChallenge-error-response.yaml	Updates schema to reflect current error set + normalizes quoting.
api/openapi/endpoints/auth_attempts/by_id/challenges/by_id/verifyChallengeProof-error-response.yaml	Updates schema to reflect current error set + normalizes quoting.
api/openapi/components/schemas/errors/tkn-invalid.yaml	Adds generated error schema for token invalid error code.
api/openapi/components/schemas/errors/tkn-invalid_tknid.yaml	Adds generated error schema for token identifier mismatch error code.
api/internal/erroranalysis/erroranalysis.go	Adds analyzer that loads packages and infers per-interface-method error constructor sets.
api/internal/erroranalysis/flow.go	Implements the intra-/inter-procedural propagation for error sets (incl. dynamic dispatch).
api/internal/erroranalysis/erroranalysis_test.go	Adds tests that pin inference behavior and call-site-sensitive dispatch.
api/generated/oas_response_encoders_gen.go	Updates generated encoders to use operation-specific typed error response wrappers.
api/generated/oas_response_decoders_gen.go	Updates generated decoders to use operation-specific typed error response models.
api/cmd/gen_openapi_errors/main.go	Switches generator to implementation-based inference and safer YAML scalar rendering.
api/cmd/gen_error_schemas/main.go	Ensures resource-prefix extraction covers var declarations (e.g., TokenPrefix).
.changeset/error-codes-in-oas.md	Adds release intent for the OpenAPI/client typing change.