API errors

Sigma has several response families. OAuth endpoints follow OAuth error conventions. Many custom routes use RFC 9457 problem JSON. Handle discovery and messageboxes have protocol-specific envelopes. Older routes can return { error, message } or feature-specific fields. Do not assume every successful response has success: true or every error has error_description.

Tolerant response parsing

export async function readApiResponse(response: Response): Promise<unknown> {
  const contentType = response.headers.get("content-type") ?? "";
  const payload: unknown = contentType.includes("json")
    ? await response.json() : null;
  if (!response.ok) {
    // Keep payload for controlled diagnostics, but do not log credentials.
    throw Object.assign(new Error(`API request failed (${response.status})`), {
      status: response.status,
      retryAfter: response.headers.get("retry-after"),
      payload,
    });
  }
  return payload;
}

Validate the successful payload against the endpoint contract before using it. Render provider messages as escaped text. Do not show internal stack traces, tokens, raw signed requests, or decrypted backup data to users or telemetry systems.

Status handling

These are common categories, not a substitute for each route's contract. In particular, certificate readiness intentionally returns 503 even for protected, and disabled handle discovery returns 503 rather than claiming the handle does not exist.

See OAuth errors, rate limits, and troubleshooting.