Handling errors

There are two error surfaces on this API and they are separated by seconds.

Synchronous. The HTTP response to your request. Something about the request was wrong, or the service could not accept it. The command was never queued and nothing happened on iMessage. The body is { "error": "<code>" }.

Asynchronous. A command event on the response stream, arriving after the command was queued, dispatched to the Mac and attempted. The body carries a status and an errorCode.

A 202 means queued. A client that treats it as delivered is not handling errors at all; it is handling the first surface and ignoring the second. Everything about a malformed payload, an unreachable recipient, a stale reply target or an unsupported capability lands on that second surface.

The decision tree

Work through it in this order. The first four branches are HTTP; the last is the stream.

A 4xx other than 429. Your request is wrong, and it will be wrong again. Fix the code, do not retry, and do not put it on a retry queue — a target_and_payload_required or an invalid_conversationId will fail identically forever. Log the code and the request that produced it. The one 4xx that is not about the body is 401 unauthenticated, which is the credential — see Authentication.

A 429. You exceeded a per-endpoint budget. Honour Retry-After (also present as retryAfter in the body, always at least 1 second) and try again. Do not back off exponentially on top of it — the header already tells you when the window reopens. See Rate limits.

A 503. Something between you and the Mac is temporarily unavailable — no connector holds a live lease, the connector is unreachable, sending is paused. These clear on their own. Back off exponentially and retry with the same Idempotency-Key. If no_live_connector persists for more than a few minutes, it is an operational problem rather than a transient one.

A 500. A persistence or unhandled failure inside the service. Retry once, with the same key, then escalate. Repeated 500s are not something a client can fix.

A 202 followed by a settlement that is not succeeded. The command reached the Mac and did not do what you asked, or could not be confirmed to have done it. What to do depends on the status and the errorCode — see the three buckets below.

Settlement codes, by what you should do

errorCode names the cause on a failed event, and often on an ambiguous or a no_effect one. It is null when the command succeeded, and the field is nullable everywhere, so branch on status first and read errorCode second. The codes sort into three groups, and the third is the one that needs a policy rather than a reflex.

Fix the request, then resend

The command was well-formed enough to be accepted but wrong by the time it ran. Nothing was sent, so a corrected resend is safe — under a new Idempotency-Key, since the payload has changed.

Retry — the effect did not happen

The command failed before or during dispatch without reaching iMessage. A resend produces one message, not two — but send it under a new Idempotency-Key. The old key stays bound to the settled command, so reusing it returns that command's terminal status and sends nothing. See Idempotency and retries.

Investigate — the effect may have happened

The Mac started the operation and could not confirm the result. These settle ambiguous more often than failed.

operator_cancelled is the odd one out: it means a person cancelled the command. It is a terminal outcome, not a failure to recover from.

A worked client

The HTTP half. It classifies the response, honours Retry-After, allows one 500 retry, caps every loop at five attempts, and reuses the same idempotency key across every attempt so a duplicate is adopted rather than executed — on the agent-turn path, which is the caveat from the callout above:

const BASE = process.env.MAPIER_BASE_URL!;

export class MapierError extends Error {
  constructor(
    readonly status: number,
    readonly code: string
  ) {
    super(`${status} ${code}`);
  }
}

export async function command(type: string, body: unknown, idempotencyKey: string) {
  let serverErrorRetries = 0;

  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${BASE}/v1/commands/${type}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.MAPIER_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": idempotencyKey,
      },
      body: JSON.stringify(body),
    });

    if (res.status === 202) return res.json(); // queued, NOT delivered

    const detail = await res.json().catch(() => ({}) as { error?: string; retryAfter?: number });
    const code = detail.error ?? "unknown";

    if (res.status === 429 && attempt < 5) {
      const wait = Number(res.headers.get("retry-after") ?? detail.retryAfter ?? 1);
      await sleep(wait * 1000);
      continue;
    }

    // 503 is transient; 500 gets exactly one retry before we give up.
    const transient = res.status === 503 || (res.status === 500 && serverErrorRetries++ < 1);
    if (transient && attempt < 5) {
      await sleep(Math.min(2 ** attempt * 500, 8_000));
      continue;
    }

    throw new MapierError(res.status, code);
  }
}

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

The asynchronous half. Only terminal statuses are ever emitted, and exactly one event arrives per command, so a switch on status covers the whole space:

const FIX_AND_RESEND = new Set([
  "invalid_target",
  "stale_target",
  "payload_conflict",
  "unsupported_capability",
  "capability_not_negotiated",
  "capability_constraint_violation",
  "invalid_session_capabilities",
]);

const RETRY_SAFE = new Set([
  "gateway_rejected",
  "send_returned_not_ok",
  "preparation_dispatch_exhausted",
  "command_claim_invalid",
  "stale_fence",
  "expired",
  "outbound_paused",
]);

type CommandEvent = {
  commandId: string;
  logicalActionId: string;
  status: string;
  errorCode: string | null;
};

export function onCommandEvent(event: CommandEvent) {
  switch (event.status) {
    case "succeeded":
      return markDispatched(event.commandId);

    case "no_effect":
      // Nothing was wrong; there was nothing to do. An already-applied
      // reaction, or a contact card that was already shared.
      return markNoOp(event.commandId);

    case "cancelled":
    case "expired":
      return markAbandoned(event.commandId, event.errorCode);

    case "ambiguous":
      // May or may not have been delivered. Never auto-resend.
      return escalate(event.commandId, event.errorCode);

    case "failed": {
      const code = event.errorCode ?? "";
      // Resends go out under a NEW idempotency key: the old one is bound to
      // this settled command and would be adopted rather than executed.
      if (RETRY_SAFE.has(code)) return scheduleResend(event.commandId);
      if (FIX_AND_RESEND.has(code)) return repairAndResend(event.commandId, code);
      // Unrecognised code: treat as a generic failure, and never as a success.
      return escalate(event.commandId, code);
    }

    default:
      return escalate(event.commandId, event.errorCode);
  }
}

Note the last two branches. Both the errorCode list and, in principle, the status list can grow, and the safe default in each case is "we do not know that this was delivered".

Related