[sentry-junior]

The OpenAPI schema for POST /organizations/{org}/issues/{issue_id}/autofix/ (startOrganizationIssueAutofix) listed only 202, 400, 401, 403 and 404, so @sentry/api types every error as unknown. The Sentry CLI and MCP in getsentry/toolkit map the 402 and 409 code values to user-facing messages, and they hardcode those codes today because the schema doesn't have them (see getsentry/toolkit#2207). Requested by @BYK.

This adds typed bodies for both statuses, with code as an enum:

• 402 AutofixPaymentRequiredResponse: detail and a required code, either seer_out_of_credits or seer_out_of_quota. Every 402 this endpoint returns sets a code: the open_pr and default-step credit and quota checks, and the pr_iteration credit check in handle_ui_feedback.
• 409 AutofixConflictResponse: detail, plus an optional code (scm_integration_required, repos_not_linked, or run_in_flight), and the optional run_id and sentry_run_id that come with run_in_flight. code is optional because some 409s carry only detail: re-running a step after a PR or coding agent started, paused PR iteration, and a run that is still being created.

The codes come from Literal types that now back the existing constants (SEER_OUT_OF_CREDITS_CODE, SEER_OUT_OF_QUOTA_CODE, RUN_IN_FLIGHT_CODE, and the keys of AUTOFIX_SETUP_REQUIRED_DETAIL). If a constant holds a code that the Literal doesn't list, mypy fails, so the enum and the runtime stay in sync. This is a typing and schema change only, with no change to runtime behavior.

The 422 that resolve_seer_run returns when a run failed to start is still undocumented. I left it out to keep this change to 402 and 409.

via @BYK.

--

View Session [Sentry]

[BYK]

Would it be possible to prevent this kind of an omission/drift with a lint rule?

[sentry-junior]

@BYK Partly. A lint rule can catch most of the omission, but not all of it. The body drift needs a type-checker or test change.

Missing statuses: a flake8 rule, similar to S021. In a method with @extend_schema, collect each Response(..., status=status.HTTP_4xx_*) or literal 4xx status it returns, and fail when that status isn't a key in responses=. That would have flagged the 402s and the setup/run_in_flight 409s here, because they're returned inline in post. It would miss statuses that come from helpers, because flake8 sees one file and one call at a time. Here that's handle_ui_feedback (402/409) and resolve_seer_run (409/422). It also can't see DRF exceptions raised deeper down. So it's a useful ratchet, not a guarantee.

Body drift: the mypy plugin is the better place. tools/mypy_helpers/plugin.py already narrows Response({...}) literals to the matching Response[TypedDict] arm. When no arm matches, it falls back, and this method's Response[ValidationErrorResponse] arm (dict[str, Any]) accepts any dict. That's why a wrong code in a 409 body wasn't a type error. I checked this while writing the PR. Narrowing that fallback, or erroring when a literal with a documented error status matches none of its TypedDict arms, would catch body drift. That probably needs a pass over endpoints that lean on the dict[str, Any] arm today.

Complete coverage: a runtime check in tests. Validate each response from endpoint tests against tests/apidocs/openapi-derefed.json. Fail when the status isn't documented for that operation, or the body doesn't match its schema. That catches the helper and exception paths too. Nothing like it exists today: the current apidocs ratchet (response_coverage.py) only checks descriptions and types of 2xx fields.

If you want one of these, the flake8 status check is the smallest. I'd start with it.