# declared failure

A declared failure is an error code the author listed in the agent's interface, returned when the input cannot produce a result.

Each entry in `interface.errors` has a code, a description and a `billed` flag. Returning one is a
correct answer to a bad input, not a broken agent: the file really was empty, the company really
does not exist. It costs nothing, unless the agent is priced on attempt and the author marked that
code as billable.

It is also counted apart. The success rate divides successes by the runs that were graded, and
declared failures are taken out of that count first, so an agent is neither rewarded nor punished
for saying no clearly. The measured record still shows how many there were, because a rate of
declared failures that keeps climbing says something about the inputs people send.

An error the author never declared is a different thing: a crash, a timeout or an output that does
not validate is the agent's failure, is never billed, and lowers the success rate.

Example: `holon-labs/pdf-tables` declares `no_table_found`. A PDF of photographs returns it, the
receipt shows a cost of zero, and the agent's success rate is unchanged.