Requests and media

Errors and retries

The error format, the codes, and which ones to retry.

Every error has the same shape: an HTTP status and one error object.

Field	Meaning
`code`	Stable, machine-readable. Branch on this.
`message`	For people. Do not parse it.
`request_id`	Also in the `x-sume-request-id` header. Quote it to support.
`retryable`	`true` when the same request can succeed later.
`retry_after_seconds`	How long to wait first, when known (also the `retry-after` header).
`next_action`	`fix_input`, `authenticate`, `retry`, `inspect_events` and similar.
`details`	Extra facts, such as the failing fields for `invalid_request`.

Codes

HTTP	`code`	Meaning	Retry?
400	`bad_request`	The body is not valid JSON.	No, fix the body
400	`invalid_request`	A field is missing or wrong. `details.errors[]` names it.	No, fix the field
400	`concurrency_limit_reached`	Your workspace has as many jobs running and queued as it may.	After a job finishes
401	`unauthorized`	No key, or the key is wrong or revoked.	No
401	`session_not_accepted`	A dashboard session was sent to the public API.	No, send a key
402	`insufficient_funds`	The open.sume.com balance cannot cover the price. `details` has `required_usd` and `available_usd`.	After a top-up
403	`open_key_route_not_allowed`	The key called a route outside the model API (list).	No
404	`not_found`	No such job or model in your workspace.	No
409	`idempotency_conflict`	The `Idempotency-Key` was used for a different request.	No, use a new key
409	`job_not_completed`	You read a result before the job finished.	Yes, poll first
409	`job_not_cancelable`	Generation has started; the job can no longer be canceled.	No
413	`payload_too_large`	The request body is too big.	No
429	`rate_limited`	Too many requests for your key in this window.	Yes, after `retry-after`
503	`database_busy`	A short overload.	Yes, after `retry-after`
500	`internal_error`	A fault on Sume's side.	Yes, with backoff

Malformed JSON is always a 400, never a 500:

Retrying safely

Retry GET requests after a network error, a 429 or a 5xx, with exponential backoff and jitter. Honour retry-after.
Retry a generate request only with the same Idempotency-Key. See Idempotency.
Do not retry 401, 403, 404 or a 400 you have not fixed.
A job that ends failed is not an HTTP error. Its error says what went wrong, and its price is refunded.