Show declines and reviews in your product
For product designers and frontend engineers: what to show for each response state so users understand a decline as a correct answer, and nobody mistakes it for an outage or a number.
Three rules
- Branch on the envelope, not the figures. Decide the screen from
computed(orstatus) andnext_action. Only acomputed: trueresponse has figures to show. - Never show a number for a declined case. No estimate, no partial total, no confidence score. The decline exists because any number would be a guess.
- Never present a decline as an error. It is a
200and a final answer. Showing “Something went wrong” or a retry button invites users to resend a request that will decline again.
What to show for each state
| State | Show | Avoid |
|---|---|---|
| Computed | The figures, the per-line derivation (or a link to it), any flags, and the legal notice. | Rounding or restating figures differently from the response. |
| Declined | “Needs preparer review” or “Outside what we can compute”, the reason, and a way to route the case to a person. | Error styling, a retry button, or any tax figure. |
| Reconcile needs review | The diff rows, highlighting DIFFERS and ENGINE-DECLINED lines, for a person to resolve. | Language that says the filed return or the engine is wrong. |
| Validation or auth error | A request problem for the developer or operator, never the taxpayer. | Exposing raw issue paths to end users. |
| Quota or rate limit | “Monthly limit reached” (stop) or a short automatic backoff (rate). | Retrying a quota error in a loop. |
Asking for affirmations
If a decline names an affirmation, only ask for it from someone who can attest to the fact, usually the preparer, and explain what they are confirming in plain language. Do not show a checkbox that a taxpayer could tick to make the decline go away. See Affirmations.
Every state, with its HTTP status, retry_safe, and next_action, is in the response-state table.
Keep a record
Store the response's code, reason, and the capability version you integrated against (from GET /api/mcp/tax-capabilities) with the case, so a reviewer can see exactly why it was routed to them.
See also: Responses & states and Declines & affirmations.