Errors and retries

An error response has an HTTP status and a JSON body with a single error object. The shape is the same for every route.

{
  "error": {
    "code": "validation_failed",
    "message": "The request has invalid fields. No changes were applied.",
    "details": {
      "fields": [
        { "field": "person_id", "problem": "must be a person ID starting with per_" },
        { "field": "text", "problem": "Invalid input: expected string, received number" }
      ]
    },
    "recovery": "Correct each field listed in details.fields, then send the request again.",
    "request_id": "req_01JC4N9F4X7Z0B3D6F9H2K5M8Q"
  }
}

Wording in message and recovery can improve over time, so don't match on it. Codes don't change. Every response, successful or not, also carries the ID in an X-Request-Id header. Keep it in your logs: it identifies the request in Rigel's own.

A rejected command is 404 when its code ends in _not_found, 403 for a role that can't run it, and 409 for everything else. See rejections. The file routes add their own codes, which the files guide lists.

A wrong path, an unknown command or query name, and the wrong method on a real path are all 404 not_found. There is no 405, so a GET on a command route looks like a missing route.

400 validation_failed means the request doesn't fit the operation's input, and it never reached the household. details.fields lists the problems, and each has a field and a problem.

• field is a path into the input: name, ingredients[2].quantity. A problem with the whole body has an empty field. A header is named in brackets, such as ["idempotency-key"] for a key that isn't a command ID.
• Every problem the schema finds is in one response. A rule that compares fields, such as "birth_date and birth_date_precision must be given together", is checked after the fields themselves pass, so fixing the first list can reveal one more.
• A malformed body, one that isn't JSON, is 400 bad_request. A body sent with another content type is 415 unsupported_media_type.

A query's parameters are validated the same way. See limits and cursors.

Each command and query lists the codes it can return on its reference page. These are the ones every client meets.

A message says whether the request took effect, and never claims more than the API knows. Rejections and validation failures end with "No changes were applied." Any 4xx on a command or query means the same thing: the request was refused, and the household is as it was.

A 500 is different. The message says only that the API could not complete the request, because the failure may have come before or after the change. Send it again with the same Idempotency-Key. The household then returns the stored outcome if the first try went through and runs the command if it didn't. It never applies it twice. The same holds when a request times out or the connection drops with no response.

Errors raised before the API runs, in the network in front of it, may not have the envelope. Read the body as JSON only when Content-Type is application/json.

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function sendCommand(household: string, name: string, input: unknown): Promise<Response> {
  const key = commandId(); // one key for every attempt of this command
  for (let attempt = 1; ; attempt++) {
    let response: Response | undefined;
    try {
      response = await fetch(`https://rigel.house/api/v1/households/${household}/commands/${name}`, {
        method: "POST",
        headers: {
          Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
          "Content-Type": "application/json",
          "Idempotency-Key": key,
        },
        body: JSON.stringify(input),
      });
    } catch {
      // No response: the request may or may not have arrived. The same key makes sending it again safe.
    }
    if (response && response.status < 500 && response.status !== 429) return response;
    if (attempt === 5) throw new Error(`Gave up after ${attempt} attempts`);
    const retryAfter = Number(response?.headers.get("Retry-After")) * 1000;
    await sleep(retryAfter || Math.min(30_000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2));
  }
}

commandId() is the helper from the commands guide. The function returns on any answer below 500 except 429, including a refusal, so the caller still reads the status and body and decides what a 404 or 409 means.