How do you handle API errors consistently across portal screens?

How do you handle API errors consistently across portal screens?

Consistent error handling helps users recognize what happened and what to do next. It should not reduce every failure to the same generic toast.

Map categories to behavior

Validation errors belong near fields. An expired session may require signing in again. A version conflict may require refreshing or merging changes. A temporary dependency failure can offer a bounded retry. Use stable API error codes instead of parsing message text.

Preserve useful context

Keep entered text and the relevant project visible. Avoid success notifications before the backend confirms the operation. Provide a safe request identifier when support needs to investigate. Test shared handling from multiple screens while checking that action-specific details remain clear. For example, failing to delete a project should not remove it permanently from the visible list, and failing to save a script should not label the draft as saved.