Errors and retries

Error format

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body.",
    "request_id": "req_0ee311b4334e4b118a94c7d1c48577fd",
    "category": "validation",
    "stage": "validation",
    "retryable": false,
    "retry_after_seconds": null,
    "public_reason": "invalid_request",
    "next_action": "fix_input",
    "details": {
      "errors": [
        {
          "path": "prompt",
          "loc": [
            "prompt"
          ],
          "message": "must have required property 'prompt'",
          "type": "required"
        }
      ]
    }
  }
}

The status gives the class: 400 fix the request, 401 and 403 the key, 402 the balance, 404 nothing there, 409 the job's state, 429 slow down, 5xx Sume's side.

Codes

Retrying safely

• Retry when retryable is true, after retry-after. Back off exponentially, with jitter, if it fails again.
• Retry reads (status, result, list) after a network error too.
• A retryable refusal frees its Idempotency-Key: send queue_full (once a job ends), provider_capacity_exceeded, provider_rate_limited or a retryable provider_submission_failed again with the same key. A final refusal keeps its answer: after insufficient_funds, top up and send a new request with a new key. A refused submit is never charged.
• Do not retry 401, 403, 404 or a 400 you have not fixed.

Idempotency

A network error after a submit leaves you unsure whether the job exists. Send an Idempotency-Key on every generate request and reuse it on retry:

Idempotency-Key: 9816bc88-9791-43a1-86c2-876dc7c544e8

• 1–255 printable ASCII characters. A UUID per request is the simple choice.
• The same key with the same body returns the original job with idempotency_hit: true, charged once.
• The same key with a different body answers 409 idempotency_conflict.

Failed jobs

A job that ends failed is not an HTTP error. The submit succeeded; the job's error object (same fields as above) says what went wrong, and its price is refunded. Reading its result answers 409 job_failed with the same reason. A model refusing a prompt on content grounds reports public_reason: "content_policy_rejected".

When a video model refuses the job or cannot use an input, message keeps the model's own sentence and public_reason names the cause: for example output_video_copyright, output_audio_copyright, input_image_real_person, edit_length_follows_input, input_image_too_small, input_aspect_ratio or prompt_too_long. Those answer next_action: "fix_input": the same request fails the same way. When the model states its limit, message names it and details.limits carries the numbers, for example { aspect_ratio: 26.67, min_aspect_ratio: 0.06, max_aspect_ratio: 16 }. Where Sume knows a model's input limits, a submit outside them answers 400 invalid_request before any job or charge, with details.reason (image_aspect_out_of_range, image_too_small, image_too_large), the field and the measured size. provider_task_timeout, provider_internal_error and provider_at_capacity answer "retry_later". New reasons may appear, so do not switch on the whole set.