Error Handling

The session and sync APIs return JSON errors with a string error field:

{ "error": "Session not found" }

There is no separate error.code or error.message property in the current REST contract.

Status	What to check
400	Required parameters such as `id` or `q` are missing
401	The Bearer API key is missing or invalid
404	The session is unavailable to the authenticated user
500	The server, a payload validator or an upstream provider failed

Validate payloads against the API reference. Some validation failures currently return 500; retrying the same invalid body will not repair it.

Read errors safely

async function fetchSessions(apiKey: string) {
  const response = await fetch("https://api.opensync.dev/api/sessions", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const body: unknown = await response.json().catch(() => null);
  if (!response.ok) {
    const message = body && typeof body === "object" && "error" in body
      && typeof body.error === "string" ? body.error : response.statusText;
    throw new Error(`OpenSync ${response.status}: ${message}`);
  }
  return body;
}

Check partial batch failures

POST /sync/batch can return HTTP 200 and ok: true with a nonempty errors array. Inspect that array before marking a batch complete. Keep external IDs stable when retrying session or message snapshots.

Retry temporary failures

Use a small, bounded number of retries with exponential backoff and jitter for temporary network or service errors. Honor Retry-After if supplied. Do not retry missing credentials or malformed payloads indefinitely. Avoid logging API keys or private message bodies.