How do you document API errors so the portal can recover?

How do you document API errors so the portal can recover?

An error contract should help the caller decide what to do next. A generic failure message alone cannot distinguish invalid input from an expired connection or a temporary outage.

Define categories and safe detail

Use application-level categories for validation, authorization, missing resources, conflicts, and temporary dependencies. Provide field-level feedback where useful and a request identifier for support. Keep secrets, raw tokens, and private provider responses out of public error payloads.

Connect errors to interface behavior

Document whether the user should edit input, reconnect an account, retry later, or stop. Preserve unsaved work when a request fails. A conflict may require refreshing the latest version rather than repeating the same update. Test that the UI handles each category without displaying a false success state. Keep diagnostic logs detailed enough to investigate while applying appropriate access and retention controls.