Predictable clients under imperfect conditions.

Pagination

Collection endpoints return a bounded page and an opaque nextCursor. Treat the cursor as an indivisible continuation token.

• Pass the returned cursor unchanged to the same endpoint.
• Keep the same filters and page size while continuing a traversal.
• Stop when nextCursor is null or absent.
• Do not decode, edit, store indefinitely, or construct cursors.
• Restart from the first page if a cursor is rejected or the query changes.

let cursor = null;
do {
  const url = new URL('https://api.uptimebasics.com/v1/monitors');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);
  const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  const page = await response.json();
  await processMonitors(page.data);
  cursor = page.pagination?.nextCursor || null;
} while (cursor);

Timeouts and cancellation

Set both a connection timeout and a total request deadline. A practical starting point is 5 seconds to connect and 15 seconds total for ordinary API reads.

• Cancel work that is no longer useful.
• Do not leave requests waiting without a deadline.
• Use a longer application workflow deadline around exports instead of holding one HTTP request open.
• A timeout is an unknown outcome for a write. Retry with the same idempotency key.

Retries and backoff

Retry only failures likely to be temporary: connection errors, timeouts, 429, and selected 5xx responses. Do not retry most 4xx responses without changing the request.

Idempotency

Mutation endpoints documented with Idempotency-Key require a unique key for each intended change.

• Generate at least 128 bits of randomness or use a UUID.
• Reuse the same key only when retrying the same method, path, and body.
• Use a new key for a later independent action, including reversing a pause.
• Persist the key with your local job until the outcome is known.
• A conflict means the key was already used with different request intent.

Idempotency prevents duplicate side effects. It does not replace authorization, version preconditions, or webhook event deduplication.

Resource versions and safe writes

Operations that expose an ETag can require If-Match. Read the resource, keep the ETag, and send it with your update. A 412 means someone changed the resource after your read; fetch it again before deciding whether to retry.

Rate limits and capabilities

Use GET /capabilities and GET /usage rather than hard-coding plan assumptions. Responses expose request IDs and applicable per-minute and monthly allowance headers.

• Log X-Request-Id for support correlation.
• Throttle before the remaining count reaches zero.
• Spread background synchronization over time.
• Prefer collection endpoints over one request per monitor.
• Never use concurrency to bypass a rate limit.

Credentials and logging

• Use a dedicated token per environment and application.
• Keep production and test credentials separate.
• Store secrets server-side in a secret manager.
• Redact Authorization, custom webhook headers, and signing secrets from logs.
• Rotate a token immediately if it appears in source control, logs, chat, or a browser bundle.
• Use selected-monitor tokens whenever an integration needs only part of an account.

Uptime Basics support will not ask for a complete API token, webhook signing secret, saved authentication password, or custom header value.