afv-library/skills/dx-devops-test-pipeline-configure/references/error-handling.md

Error Handling — All Modes

Never expose raw API error messages, stack traces, or JSON payloads to the user. Map response status codes to plain-language messages.

Mode A — Configure a test provider

Status	User-facing message
400	"The request was invalid. Check that the provider ID and pipeline ID are correct."
403	"You don't have permission to configure test providers on this pipeline."
404	"The pipeline or test provider was not found."
409	"That provider appears to already be configured on this pipeline. To pick up new suites, re-sync it instead."
500	"A server error occurred. Try again in a few minutes."

Mode B — Sync a configured provider

Status	User-facing message
400	"The sync request was invalid. Check that the provider ID and pipeline ID are correct."
403	"You don't have permission to sync test providers on this pipeline."
404	"The pipeline or test provider was not found."
500	"A server error occurred. Try again in a few minutes."

Mode C — Configure a quality gate

Status	User-facing message
400	"The quality gate configuration is invalid. Check that all rule types and thresholds are correct."
403	"You don't have permission to configure quality gates on this org."
500	"A server error occurred. Try again in a few minutes."

Prerequisite / environment errors

Error condition	Response
sf org list fails entirely	"Could not reach the Salesforce CLI. Make sure sf is installed and on your PATH."
sf org display returns auth error	Surface plain-language re-auth instructions. Do not expose the raw error.
DevopsPipeline query fails with 5xx	"The DevOps Center org is returning a server error. Try again in a few minutes."
Any check throws unexpectedly	"Something went wrong checking prerequisites. Error: [plain summary]. Let's try again — or resolve it manually and let me know when ready."