Map Sume API error codes to messages your app's users can act on

Show users a short instruction that matches what they can change, and keep the Sume code and request_id in your logs. Most Sume errors are not the user's fault: a 401, 503 or queue_full is your service's problem, and the user should only see "try again in a moment".

This table splits the documented codes by who can fix them. The codes come from the Sume errors page, read 2026-10-10.

The translation table

Keep two layers

Give the UI a small enum of your own, such as fix_input, ask_owner, retry_later and contact_support, and map Sume codes onto it in one place. The front end then never branches on a vendor string, and a new Sume code falls into contact_support by default instead of breaking a screen.

Failed jobs carry their own public error metadata (category, retryability, next action). Prefer the job's next_action field over guessing from the category, and use the job error categories post for the retry side.

• Never render the raw message to end users; it is written for developers.
• Log request_id with every failure so support can find it.
• Do not put API keys, signed URLs or raw media URLs in a user-visible error or a ticket.

Credits need a special case

A 402 is the one error where the right message depends on the viewer. The workspace owner can act on it; a team member cannot. Check the role before you show a "Top up" button, and for everyone else say the feature is temporarily unavailable. The balance route lets you check before submitting, so a warning banner can appear before any user hits the wall.

Test the mapping

Treat the mapping as code with tests. A simple table-driven test feeds each documented status and code pair through the function and asserts the enum it returns, plus one unknown code that must land on contact_support. Add a case where the body is not JSON at all, because a proxy or a client-blocking layer can answer with plain text, as the urllib 403 post shows.

Review the table when the Sume errors page changes, and keep the copy in one file so that a product writer can change the wording without touching the control flow.

• One test per documented code.
• One test for an unknown code.
• One test for a non-JSON body.
• One test that a 402 shown to a non-owner never contains the word balance.