Founders
How to define acceptable failure modes for AI developer APIs
AI developer APIs: Define unacceptable failures in the language of the customer workflow.
Define unacceptable failures in the language of the customer workflow. Some errors can be corrected cheaply; others need a stop or escalation even when rare. A blended accuracy percentage can hide that difference.
Start with the decision
List failure categories, consequences, detectability, and recovery ownership. Build evaluation examples for the most consequential categories. Ask the buyer what must never happen automatically, and document where human authorization remains required.
The illustrative scenario
This is an educational workbook. The company or fund and all numerical inputs below are fictional. They are not ADIN results, customer claims, market benchmarks, or a forecast.
The fictional API transforms uploaded documents into structured fields for a developer integrating an operations system. The developer controls implementation, but an operations owner decides whether the extracted output is usable.
A successful HTTP response does not prove that a field is correct. Changes in document layout, retries, and ambiguous inputs need visible behavior and a defined fallback.
An evaluation sample with a denominator
Imagine a permissioned evaluation set with 43 cases and 30 that meet a rubric defined before the test. The resulting percentage describes only this invented sample. Seventy percent is not a recommended target, a safety standard, or evidence about any real system. What matters is the rubric, sample coverage, and consequences of the remaining cases.
A successful HTTP response does not prove that a field is correct. Changes in document layout, retries, and ambiguous inputs need visible behavior and a defined fallback. Break the 13 remaining cases into failure categories before interpreting the aggregate. A recoverable wording issue and an unauthorized action may require different product behavior even when both count as a failed case. Keep reviewer disagreement and missing evidence visible.
The assumed time comparison is 6 minutes before and 4 minutes after, including the stated human step. Validate the same start and end points in a real study, then include retries, repair, and handoffs. Compare a successfully consumed record with the current integration. Include retries, validation failures, and support time in both the quality and cost discussion. A short average time is not enough if the result cannot be used or trusted.
| Item | Illustration |
|---|---|
| Invented evaluation cases | 43 |
| Cases meeting the fictional rubric | 30 |
| Cases requiring investigation | 13 |
| Observed proportion in this exercise | 69.8% |
| Assumed human minutes before / after | 6 / 4 |
Use this worksheet
Answer the questions with a source, date, owner, and next action. Mark an unknown as unknown. Use public or permissioned information and involve a qualified specialist when a question requires expertise beyond the team’s competence.
- What can go wrong?
- Who bears the consequence?
- Can the error be detected?
- How is the action reversed?
- Which case requires escalation?
Questions specific to this scenario
- What constitutes a valid record?
- How are retries identified?
- Who owns changes to the output contract?
Use versioned input fixtures, field-level expected outputs, retry logs, and integration support requests. Keep test data provenance and access permissions attached to the examples.
A concrete next test
Trace a successful record, a malformed input, and a retry through the consuming application. Ask the integrator where an error becomes visible and who can repair it. Include the downstream validation step when defining completion and measuring cost.
Interpret the result
A failure taxonomy should change product behavior and testing priorities. It is not a certificate of safety. Revisit it when the system gains new data, permissions, customers, or the ability to take actions.
Compare a successfully consumed record with the current integration. Include retries, validation failures, and support time in both the quality and cost discussion.
Sources and method
These primary resources provide background for the concepts. The fictional scenario, calculations, and worksheet are ADIN educational examples; the sources do not report or validate those invented results. Reviewed October 11, 2026.