3.Visitor Passes and Delivery Notes

The Problem in Real Life

"It Either Works or It Doesn't" vs. Clear Rules for Every Kind of Failure

API Authentication, Authorization, Errors and Status Codes

• API authentication — the visitor pass: APIs check who is calling, usually with one of: an API key (a secret string for a program, Act 22), a bearer token such as a JWT for a logged-in user (Act 22), or OAuth client credentials — a program logs in with its own ID and secret and gets a short-lived token, the standard for machine-to-machine calls. Webhooks are usually authenticated with a signature (chapter five).
• API authorization — which floors: the pass also limits what the caller may do, often with scopes: a venue's API token has the scope sales:read for its own venue only — it can't read other venues or issue refunds (least privilege, Act 22).
• Status codes — the note's headline: 2xx = it worked: 200 OK, 201 Created, 202 Accepted ("got it, will do it later"), 204 No Content. 4xx = the caller did something wrong — don't retry the same request: 400 Bad Request, 401 Unauthorized (who are you?), 403 Forbidden (not allowed), 404 Not Found, 409 Conflict (the seat is already taken), 422 Unprocessable (valid JSON, invalid values), 429 Too Many Requests (slow down). 5xx = the server had a problem — trying again later may work: 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout.
• Error bodies — the note's details: a good API returns a consistent JSON error with a machine-readable code, a human message, which field was wrong, and the request ID for support. Never include stack traces or secrets (Act 17, Act 22).
• Timeouts — how long to wait: every API call needs a timeout: the longest the caller will wait. Without one, a slow provider can freeze your whole app. The payment provider waits 10 seconds for BlueTicket; BlueTicket waits 5 seconds for the SMS provider.
• Retries with backoff — try again, politely: for timeouts, 429 and 5xx, retrying often works. But retry with exponential backoff — wait 1 second, then 2, then 4, then 8 — plus a little randomness, so thousands of clients don't all retry at the same instant. Don't retry most 4xx errors: the same wrong request will fail the same way.
• Idempotency keys — retries without double charges: a POST that timed out might have worked — the answer just got lost. Retrying could create a second charge. So payment APIs accept an idempotency key (Act 12's idempotency): a unique ID sent with the request. If the same key arrives twice, the provider returns the first result instead of doing it again.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "seat_unavailable",
    "message": "Seat C14 is no longer available.",
    "field": "seatIds",
    "requestId": "req_9f2a71"
  }
}

const idempotencyKey = `order-${order.id}`;          // same key on every retry

for (let attempt = 1; attempt <= 4; attempt++) {
  try {
    return await payments.createPayment(
      { amount: order.total, orderId: order.id },
      { idempotencyKey, timeoutMs: 5000 }
    );
  } catch (err) {
    const retryable = err.isTimeout || err.status === 429 || err.status >= 500;
    if (!retryable || attempt === 4) throw err;
    await sleep(2 ** attempt * 500 + Math.random() * 250);  // 1s, 2s, 4s... + jitter
  }
}