longrun.
Errors and retries

Docs

Essentials / Errors and retries

Errors and retries

Let’s read the response together and work out whether to fix the request, wait, or try again.

1. Check whether the request was accepted

If you didn’t get a successful response, start with error.code and error.message. For example, a 401 usually sends us back to the API key: was it copied correctly, and is it still active?

A 404 means we should check the ID and whether it belongs to this workspace. Correct that problem before sending the same request again.

Example request error
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

2. Check whether the work finished

A request can be accepted and still fail during processing. Use the run ID to ask for its status. HTTP 200 means the status request worked; it does not mean the processing succeeded.

Look for completed, failed, or cancelled in status. If it failed, read error.message and open the run in LongRun for its step details. That is where we find what to change.

Check the run
curl --request GET "https://api.uselongrun.app/v1/runs/${RUN_ID}" \
  --header "Authorization: Bearer ${API_KEY}"
Failed run · illustrative
{
  "id": "run_example",
  "status": "failed",
  "outputs": null,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Check the supplied input."
  }
}

3. Avoid doing the same work twice

Sometimes your connection drops before you receive a response. You may not know whether LongRun accepted the request. An Idempotency-Key lets you resend that same request without asking for a separate run.

For the receipt below, we’ve chosen receipt-1042-v1. Keep that key when retrying the identical request, but choose a new unique key for a new document. Changing the request while keeping the key causes a conflict.

Retry the same submission safely
curl --header "Idempotency-Key: receipt-1042-v1" --request POST "https://api.uselongrun.app/v1/pdf/html-to-pdf" \
  --header "Authorization: Bearer ${API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
  "inputs": {
    "html": "<h1>Receipt 1042</h1>"
  }
}'

4. Decide whether to retry or cancel

If a failed or cancelled run is eligible for retry, the first request below asks for a new run. Keep its new ID and check its progress. A retry won’t fix bad input; submit a corrected request if the data needs changing.

The second request asks to cancel a run. Check its resulting status rather than assuming cancellation happened immediately.

Retry an eligible run
curl --request POST "https://api.uselongrun.app/v1/runs/${RUN_ID}/retry" \
  --header "Authorization: Bearer ${API_KEY}"
Request cancellation
curl --request POST "https://api.uselongrun.app/v1/runs/${RUN_ID}/cancel" \
  --header "Authorization: Bearer ${API_KEY}"