Errors

Every API error has the same shape. Branch on its code, never on its message.

The shape

A success is {"data": …}. A failure is {"error": …}, even for a mistyped path (404 NOT_FOUND) or a wrong method (405 METHOD_NOT_ALLOWED).

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "…written for a person; may change",
    "details": { "field": "name" }
  }
}

Every answer carries an X-Request-ID header. Quote it when you report a problem. On a self-hosted installation, it is the request_id in the logs.

code

A stable name in capitals, such as CONCURRENCY_LIMIT. Branch on it.

message

One sentence for a person. It uses the installation’s own words and may change.

details

An object, on some errors: what a program can act on, such as the wrong field, the missing permission, the switch that is off or why a token ended (reason). Its keys depend on the code.

Branch on the code

Decide by status first, then by code. Retry only what says to retry, and wait as long as Retry-After asks when it is sent.

const res = await fetch(url, { method: "POST", headers, body });
const answer = await res.json();

if (!res.ok) {
  const { code, message } = answer.error;
  const retryAfter = res.headers.get("Retry-After");
  if (retryAfter) {
    // a 429 or 503 that says when: try again after that many seconds
  } else if (res.status === 429) {
    // CONCURRENCY_LIMIT or RUNS_WAITING_LIMIT: try again when a run finishes
  } else if (code === "PAUSED") {
    // a self-hosted installation without a license: don't retry
  } else if (code === "CONFLICT") {
    // publish the workflow first, or wait for the other request
  } else {
    throw new Error(`${code}: ${message}`); // fix the request
  }
}

res = requests.post(url, headers=headers, json=body)

if not res.ok:
    error = res.json()["error"]
    retry_after = res.headers.get("Retry-After")
    if retry_after:
        pass  # a 429 or 503 that says when: try again after that many seconds
    elif res.status_code == 429:
        pass  # CONCURRENCY_LIMIT or RUNS_WAITING_LIMIT: try when a run finishes
    elif error["code"] == "PAUSED":
        raise RuntimeError("Load a license first")  # don't retry
    elif error["code"] == "CONFLICT":
        pass  # publish the workflow first, or wait
    else:
        raise RuntimeError(f"{error['code']}: {error['message']}")

What to do, by status

A 503 SERVICE_UNAVAILABLE means the database or Redis didn’t answer, so your token and the address weren’t checked. Only a token or an address that really isn’t there answers 401 or 404.

Error codes lists all 75 codes, with the calls that send each one.

When an installation is paused

A self-hosted installation runs only while a valid, unexpired license is loaded. Without one, a call with an API token made in GoRunner answers 503 PAUSED, and nothing is read, written or run. A token made inside a partner’s product answers 403 EMBED_NOT_AVAILABLE instead.

Calls work again within a second of loading a license, or within a minute if Redis is down. GoRunner Cloud never pauses.

Related: Idempotency · Authentication · Error codes · Check a definition · Workflow definition · Your license