Application Programming Interface Errors and Safe Recovery

Interpret errors within the operation’s application programming interface (API) contract. The same status can describe different resources and corrective actions. Interpret Hypertext Transfer Protocol (HTTP) statuses alongside the response body. Retain the method, path, status, safe response body, and timestamp. Keep credentials and sensitive request values out of escalation evidence.

Common HTTP Status Codes

Use this table to interpret common HTTP status codes and identify a response:

For draft commands, a non-draft token normally produces 400. A stale draft token normally produces 409, not uniformly 412. Archive uses the policy token. Reconciliation uses the ownership-registry token. Refer to conditional requests.

An operations 404 can mean no recorded deployments. A diagnostics 404 can mean expired evidence. A saved-validation 404 can mean no draft. Read the status-code description for the endpoint you called before deciding what to retry.

Error Response Shapes

Common service errors use message and optional causedBy fields. Workflow errors use detail, which can contain a string, object, or validation list. Do not assume every error contains detail.code.

Compile, submission, and approval can return structured validation failures. The following example illustrates an approval failure. Do not expect its code from every operation:

{
  "detail": {
    "code": "approval_validation_failed",
    "message": "Approval cannot continue until the validation findings are resolved.",
    "conflicts": [],
    "issues": [
      {
        "path": "$.user_attribute",
        "constraint": "required",
        "message": "Set the identity source user attribute."
      }
    ],
    "supportReference": "VAL-example"
  }
}

An authorized auditor can retrieve retained evidence through validation diagnostics. Records expire after seven days. The support reference itself does not authorize access. If you lack policy:audit, retain the safe failure response and reference for an authorized auditor. Compare each issues[].path with the request schema for the endpoint. If the message describes an identity-source setting, as in the example, send it and the support reference to the identity integration administrator. Do not add an unfamiliar configuration field to your policy request merely because the error names it.

Draft conflicts can include detail.currentDraft, with the current etag, currentVersionId, and draft identity. Reload policy detail and compare the saved draft with your intended changes before retrying. Archive-evidence location conflicts can include detail.unexpectedLocationIds. Ownership conflicts can include the changed affected-policy set or revision map. Ordinary schema failures can contain a validation-error list instead. For a changed draft, read current content and validation with the required authority. Correct the selected input or review the new findings before resubmitting. After retrying, reload the policy to check the saved content and status. For publication failures, follow the delivery verification guides.

Retry and Idempotency Guidance

No general idempotency key makes every lifecycle command replay-safe. After a timeout, first read current policy, history, and permitted operation evidence. The server might have accepted a command before the connection failed.

Reconciliation decisions require an Idempotency-Key. An identical accepted decision can replay without another ownership transition. Keep the original actor, body, registry token, and key for that exact replay. Changed evidence requires inspection and a new decision.

Retained deployment retry requires no general idempotency key. It restarts eligible work that stopped after failure. A repeated request can return 409 while that work is already running again. Archive-evidence submission can append another immutable event when repeated. Check history before repeating it after an uncertain result.

Endpoint Groups and Expected Error Patterns

Use this table to identify the correction boundary for each operation family:

Only acknowledge conflicts that explicitly permit acknowledgement. Never acknowledge a hard validation failure or shared-protector permission widening. An author without review capability cannot use saved validation as an unrestricted diagnostic shortcut. An operator may need to repair integrations before the author can continue.

For ownership mismatches, use explicit reconciliation inspection and allowed decisions. Do not assume waiting for a background refresh authorizes adoption or replacement. Retrying delivery reuses retained artifacts. It does not compile corrected drafts. There is no public run-now endpoint for automatic recompilation.