<span id="管理工单错误异步状态与环境"></span>

# Administrative ticket errors, asynchronous states, and environments

| Stage | Error shape or boundary |
| --- | --- |
| Authentication | String code/msg; X-API-Key is inapplicable. Handle 401/403/503/500 according to the actual identity stage. |
| List parameters and PATCH decoding | HTTP 400 with numeric code:2 and message; do not replace all such errors with ErrParamInvalid. |
| Service failure | code/msg/data:null; text is usually localized. 404/400/409/503 and similar statuses depend on the error classification. |
| Title/body validation | writeTextFieldError matches first: 422/ErrFieldRequired or ErrFieldTooLong. details includes field and reason; oversized text also includes string limit, actual, and unit:unicode_code_point. The original body is not echoed. |
| Request decoder | Regular Decode does not strictly reject unknown keys, trailing JSON, or duplicate keys. These handlers also do not set a common body size limit. |

The final GitHub title allows up to 256 code points and the body 65536. Creation normalization removes old markers, trims whitespace, and adds the current marker. Limits include the final marker. bug/feature draft titles include a prefix, counted in the limit. auto generation truncates and marks facts, but this does not imply arbitrary submissions are automatically truncated.

The draft template detects and replaces sensitive content under current rules. Creation requests run detection again and reject matches. The category list is not a complete privacy guarantee; an empty sensitive_findings array does not justify immediate external publication. A draft also does not prove that external creation is configured in this deployment.

<span id="奖励审批"></span>

## Reward approval

The approval transaction locks the ticket, validates the stored UC principal, updates the ticket as needed, and reuses or creates a unique event. It accepts no amount. A separate detail read follows the commit; directory or read failures may return an error after the commit. GET details first to confirm reward_event and ticket status rather than resending because of an HTTP error. Repeated calls reuse the previous approver and event but may still change status/admin_reply supplied in the request.

pending only means waiting for consumption. Approval is not an ordinary reversible configuration. These APIs provide no operation to revoke approval or delete the event.

<span id="github创建"></span>

## GitHub creation

Valid input is checked before local state. created reuses the primary Issue; pending/creating returns a conflict; failed requires explicit retry. A retry freezes new content and generates a new request_id. retry is not a general idempotency key, and the API does not accept a caller-supplied request_id. A ticket's primary Issue does not permit unrestricted repeated creation.

Before enqueueing, the service prepares the configured workspace owner and valid role, locks and checks again, and persists the request and event. A 202 response does not synchronously create an external Issue. Background execution rechecks the frozen identity, role, and payload. Check actual state through github_issue in GET administrative ticket. created requires issue_number/issue_url; failed exposes last_error_code. These APIs currently provide no dedicated cancellation, deletion, or query by request_id.

If an external creation receipt was obtained but local saving failed, a timeout or HTTP error alone cannot establish that creation did not occur. Have the responsible owner check associated receipts and execution records before repeating. Subsequent independent triage should preserve an existing creation receipt.
