Handle errors and retries

Two kinds of thing go wrong. A request can be refused: the API answers with an error status, and nothing has started or been charged. Or a run can start and then fail at a step. This page covers both, and when it is safe to try again.

What an error looks like#

An error answers with a status code and a JSON body. Almost every body has an error field with a message in plain words, and some add fields that explain it. One does not: a workflow that fails validation when you start a run answers 422 with success and errors, and no error field. Check the status code first, then the body.

{
  "success": false,
  "errors": [
    { "message": "'Image generator' missing required input: Prompt", "nodeId": "7c41…" }
  ]
}

Every status, and what to do#

Each endpoint's own answers are listed in the API overview. By status:

400 Bad request#

• What it means: Only Create a workflow answers this: the body has no name, no steps, or not exactly one of agentId and projectId.
• What to do: Fix the request body. The error names what is missing.
• Retry: Not until the request is fixed.

401 Unauthorized#

• What it means: The key is missing, malformed, unknown, revoked or expired.
• What to do: Send Authorization: Bearer sk_live_… with the whole key. If the key was revoked or lost, create a new one.
• Retry: No.

402 Payment required#

• What it means: A limit on spend refused the run. Read error: not enough credits (required), the key's monthly cap (monthlyCreditCap), the project's hard cap (hardCap), or a step over your team's per-step ceiling (ceiling).
• What to do: Buy credits, wait for the cap to reset, or change the limit or the workflow. See Cap your spend.
• Retry: Not until the limit or the balance has changed.

403 Forbidden#

• What it means: The key does not have the scope this endpoint needs, or it is limited to other workflows.
• What to do: Use a key with the scope named in the reference for the endpoint.
• Retry: No.

404 Not found#

• What it means: Nothing with this id exists in your team. An id from another team reads the same way. Starting a run also answers this for a workflow with no canvas.
• What to do: Check the id, and that the key belongs to the team that owns it.
• Retry: No.

409 Conflict#

• What it means: The workflow already has a run in progress. activeJobId is that run.
• What to do: Read the run in activeJobId and wait for it to end, then start yours; or use its result if any run will do.
• Retry: Yes, once the run in progress has ended.

422 Unprocessable content#

• What it means: The request is well formed but cannot run: an inputs name the workflow does not have (validKeys lists the ones it has), a callbackUrl that is not https, a step list that is not a valid workflow, a workflow that fails validation, or a step that can only run on a provider not available through the API yet (providers names it).
• What to do: Fix the request or the workflow. A validation failure lists each problem in errors. For a provider not available through the API, pick another provider on that step, or run the workflow from the app.
• Retry: Not until the request or the workflow is fixed.

429 Too many requests#

• What it means: Too many requests with this key: by default, 60 a minute.
• What to do: Wait for the number of seconds in Retry-After, and poll less often.
• Retry: Yes, after Retry-After.

500 Server error#

• What it means: Something failed on Sushibelt's side.
• What to do: Retry a read. Before retrying a run, check whether it started: a retry that answers 409 names the run in activeJobId.
• Retry: Yes, with care for starting runs.

503 Service unavailable#

• What it means: The key has a monthly cap that could not be checked just now, so the run was refused rather than started unmetered.
• What to do: Wait for the number of seconds in Retry-After.
• Retry: Yes, after Retry-After.

Which requests are safe to repeat#

When a run fails#

A run fails when any step fails. The failed step has an error that says why; the steps that depended on it are skipped. Steps that finished stay charged — their outputs exist and are in your library — and every step that did not finish is refunded.

{
  "jobId": "8b2d6f10-4c3a-4e59-a7d2-91f0c3e8b5a4",
  "status": "failed",
  "progress": 33,
  "steps": [
    { "node_id": "0d9e…", "step_type": "TextEntry", "status": "completed" },
    { "node_id": "7c41…", "step_type": "DiffusionWorker", "status": "failed",
      "error": "The provider refused the request: the prompt was empty." },
    { "node_id": "c3a8…", "step_type": "GithubDelivery", "status": "skipped" }
  ],
  "output": []
}

Common causes, all named in the step's error:

• The provider refused the request or the input, or was unavailable.
• A step would have cost more than your team's per-step ceiling.
• A delivery step could not write to its repository: no token, no access, or no such branch.

Resume a failed run#

The API cannot resume a run yet. Starting the workflow again runs every step again and charges for each. To keep the steps that finished and pay only for the rest, continue the run in the app:

1. Open the agent in the app, and its Runs list.
2. Open the failed run on the canvas.
3. Choose Continue. The failed step and the steps after it run again; the steps that finished are reused, not run or charged again. Start over runs everything again instead.

A run you continue keeps its jobId, so code that reads it sees it progress again.