Map your Sora error handling onto Sume's error envelope

Rebuild your error handler around Sume's error.code and request_id, not around message text. The errors guide says every error body carries a structured envelope with a code, message and request id that is safe to share with support. Codes decide behavior: invalid_request means fix the input, insufficient_credits means stop, queue_full and rate_limited mean back off, and provider_capacity_exceeded means retry with the same idempotency key.

From status code to action

A handler that only checks HTTP status loses information, because 429 has two meanings and 409 has several. Switch on error.code.

Headers worth reading

Public responses can carry ratelimit-limit, ratelimit-remaining, ratelimit-reset and retry-after. Use retry-after when present, and slow your submit loop as ratelimit-remaining approaches zero rather than waiting for the 429. The guide is explicit that unsafe submit requests should not be retried without an Idempotency-Key.

Log the request id, nothing sensitive

Store error.request_id next to your own job record so a support request is one lookup. The guide says not to include API keys, signed URLs, raw media URLs or private workspace ids when reporting an issue, so scrub those from logs before you paste them.

Job errors are separate

A job can fail after a clean 202. Failed jobs expose public error metadata such as category, stage, retryability and a next action, and the admission guide lists the reservation behavior. Handle submit errors and job errors as two layers, and keep your Sora-era retry decorator only for the first.