Troubleshoot Authoring and Review

Use this task when saving, submission, review, or approval fails. Application programming interface (API) callers must retain response headers and details. An existing governed revision can remain current while replacement draft work fails. Do not infer a delivery failure from a draft validation error.

Prerequisites

Prepare the following:

• Identify the policy and the exact action that failed.
• Use your own authenticated identity.
• Read roles and permissions.
• Retain the returned error and any support reference.

Check Permissions Before Retrying

Check these separate authorization requirements:

1. Identify the command’s required capability. Submission requires policy:edit. Requesting changes requires policy:review. Approval requires policy:approve.
2. Check applicable policy access grants for authoring. Edit authority alone does not replace an active owner or editor grant.
3. Ask a Protegrity Provisioned Cluster (PPC) user with administrator permissions to correct a missing command permission. For a missing owner/editor grant, ask an existing owner of that policy.

Ownership does not grant review or approval capability. An author role does not create review authority. Use your deployment’s approved authority mapping. Do not request broad administration by default. A reviewer describes a responsibility, not a separate policy_reviewer product role.

Different users can author, review, and approve. Policy does not impose a universal two-person approval requirement. Follow any additional separation-of-duties rules in your organization.

Use the Token for the Resource You Change

An authentication token proves caller identity. A resource validator identifies the version you inspected. Do not interchange them.

Use this table to identify the resource evidence required for each task:

Complete the following steps:

1. Read the current policy with GET /policies/{policy_id}. Keep both response validators distinct.
2. Compare the current draft with the content you intended to change. Resolve another user’s changes before attempting your decision again.
3. Obtain the current saved validation as an authorized reviewer. Use GET /policies/{policy_id}/validation. It requires policy:review.
4. Use the current reviewed draft token for the intended draft command. Do not construct it from a visible version number.
5. Read GET /policies/{policy_id} again. Check that the draft status reflects your command and that the saved content includes your intended changes.

An author without review authority must hand validation inspection to a reviewer. After submission, the reviewer must reload the submitted draft and use its new Draft-ETag value. The author’s pre-submission token is no longer the review token.

A missing token can return 428. Draft commands can return 400 for the wrong token kind or 409 for a changed head. Request-changes reports a mismatched token as 409. Archive can return 412 for stale governed-policy evidence. Read the response. Do not treat every 409 as the same failure.

Resolve Validation and Conflict Findings

Complete the following steps:

1. Read the returned error message and each issue’s path and message. If an issue names a policy field, compare that field with the request you sent.
2. Correct draft fields that you control. Resolve blocking conflicts rather than treating every finding as an acknowledgement choice.
3. Send directory, connection, or discovery errors to the administrator of the named integration. Include the error and support reference. Do not change unrelated policy fields to clear an integration error.
4. Save corrected work through the normal authoring task. Saving does not submit or approve the policy.
5. Ask an authorized reviewer to refresh validation for the saved head. Current dependencies can change findings even when draft text remains unchanged.
6. Submit or review through the lifecycle tasks. Acknowledge only permitted findings with the required notes and current conflict identifiers.

Hard permission-widening conflicts do not become safe through acknowledgement. Missing classification, protector, or identity evidence can require an external owner. Refer to restricted diagnostics when an auditor must inspect configuration details.

Handle Returned Work and Approval

When a reviewer requests changes, the author should retain the reason. Correct and save the draft before resubmitting eligible current work. The reviewer uses their own authenticated account for the next decision. Policy derives actor identity from authentication. Do not send submittedBy, approvedBy, or spoofed identity headers.

Approval queues publication. It does not prove delivery or protection. If approval succeeds but delivery stalls, switch to publication recovery. Do not repeatedly approve merely because protection remains incomplete.

Verification and Stop Conditions

Reload the policy and check the saved content, draft status, and recorded decision actor. After approval, follow the delivery verification guides.

Use the diagnostic handoff if you cannot obtain the required permission, current validator, or integration details. Do not discard another user’s work, override hard conflicts, or share credentials.

Refer to API authentication and API operation reference for exact request contracts.