Errors and retries

The API uses standard HTTP status codes. Every error has a JSON body with a message saying what went wrong, and a code naming the problem:

{
  "error": "Execution not found",
  "error_code": "not_found"
}

Decide what to do from error_code. It names the problem and never changes, while the wording of error is for people and may be improved. The error codes below list every one.

Request IDsCopy Anchor Link

Every response, error or not, carries an X-Request-Id header naming the request:

X-Request-Id: req_9808efd9bf000072c581da45b425d3c0

When something goes wrong and you contact Lodol's support, quote it: it finds the request in Lodol's records. Log it with any error you keep.

Status codesCopy Anchor Link

Error codesCopy Anchor Link

These name a problem precisely, so your code can handle each its own way:

Any other error has the code for its kind of problem: invalid_request (400), unauthorized (401), licence_required (402), forbidden (403), not_found (404), method_not_allowed (405), conflict (409), request_too_large (413), unprocessable_request (422), internal_error (500) or service_unavailable (503).

Common errorsCopy Anchor Link

Retry safelyCopy Anchor Link

Retry 409, 5xx, and 429 with the code rate_limited, waiting longer each time. When the response has a Retry-After header, wait that many seconds; otherwise back off exponentially. Don't retry other 4xx responses: the request itself needs fixing. Nor the other 429s: concurrency_limit clears only when a run finishes, and monthly_run_limit when the month's runs come back.

async function lodolRequest(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(url, options);
    const code = response.status === 429 ? (await response.clone().json()).error_code : null;
    const retryable =
      response.status === 409 || response.status >= 500 || code === 'rate_limited';
    if (!retryable || attempt === maxRetries) return response;

    const retryAfter = Number(response.headers.get('Retry-After'));
    const seconds = retryAfter > 0 ? retryAfter : 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

Retry a request that starts a run only with an idempotency key, or a timeout could start the same run twice.

IdempotencyCopy Anchor Link

POST requests, Run a workflow and Stop a run, accept an Idempotency-Key header. Lodol remembers the response to the first request with each key, and returns that same response to any later request with the same key, instead of doing the work again.

curl -X POST https://api-prod.lodol.com/api/v1/workflows/665f1a2b3c4d5e6f7a8b9c0d/run-async \
  -H "Authorization: Bearer $LODOL_API_KEY" \
  -H "Idempotency-Key: order-1042-confirmation"

• Make the key from what the run is for, such as your own order or event ID, so a retry of the same work always sends the same key. Keys can be up to 256 characters.
• Responses are kept for 24 hours. A repeated request in that time gets the first response back, with an X-Idempotent-Replayed: true header.
• Requests in flight return 409. If the first request with a key is still being processed, a second one gets 409 Conflict with Retry-After: 5.
• A key belongs to one request. Reusing a key for a different request, such as the same workflow with different inputs, returns 422.

DELETE requests take no idempotency key. Deleting a workflow or a run that's already gone returns 404, so check with Get a workflow or Get a run before retrying a delete that timed out.