PBJ SDK documentation

HTTP transport

Learn how the SDK builds requests, authenticates, parses responses, applies deadlines, and safely retries read operations.

Request lifecycle

  1. Validate inputs and encode path identifiers.
  2. Append the resource route and serialize query values.
  3. Create an internal AbortController and total deadline.
  4. Send bearer-authenticated JSON through Fetch.
  5. Retry eligible GET responses while time remains.
  6. Parse success data or map failure metadata to a typed error.
  7. Clear timers and abort listeners.

Wire format

http
GET /v1/projects?limit=20 HTTP/1.1
Host: api.pbjspace.dev
Authorization: Bearer pbj_••••••••
Accept: application/json
  • Query values are strings, numbers, or booleans; undefined values are omitted.
  • Requests with bodies also send Content-Type: application/json.
  • Fetch uses redirect: "error" and credentials: "omit".
  • Successful empty responses return undefined.

Retry policy

OutcomeRetry?
GET → 429, 500, 502, 503, 504Yes, while attempts and deadline remain
POST, PATCH, DELETE failureNo
Authentication or validation failureNo
Fetch/network failureNo
Malformed success JSONNo
Caller cancellationNo
text
jitter = 0.5 + random() × 0.5
fallback_ms = retryDelay × 2^retryIndex × jitter
wait_ms = min(maxRetryDelay, selected_delay)

Total deadline

The timeout covers every attempt, response-body read, and retry wait. A timed-out mutation may still have completed on the server, so read the current state before submitting it again.