HTTP, JSON, APIs, secrets, and failure handling

What you will be able to do

1. Interpret request/response behavior and status codes.
2. Implement bounded retry and timeout decisions.
3. Keep credentials and protected bodies out of logs.

Prerequisites: dictionaries, loops, functions, exceptions and installed Python or paper tracing. Reuse earlier Builder artifacts only when the task requires them.

This curriculum runs self-study on VetsLearn. Where the text calls for an instructor, peer or formal review, use the stated acceptance criteria for self-review. Reflection questions support reflection; they do not replace independent assessment. A peer review is optional unless your actual organization requires it.

Part 1 Technical instruction

An API client is a reliability and security boundary. A request needs a method, endpoint, headers, payload, timeout, and request identifier. Responses have transport success, protocol status, and application semantics; a 200 response can still contain invalid JSON or an invalid business object. Retry only transient failures, respect Retry-After, add jitter to avoid synchronized retries, cap attempts and total time, and never retry a non-idempotent action without an idempotency design. Secrets enter through an approved runtime mechanism and must never be returned in exceptions or telemetry.

Mechanism and implementation

Separate transport, protocol and application outcomes. Retry policy depends on operation semantics as well as status, deadline, jitter and Retry-After. A timed-out write may already have succeeded: reconcile before retrying. Authentication failures require corrected credentials or a human decision.

Constructed offline example

Save as topic_example.py and run python topic_example.py with an installed Python 3.11+ interpreter. This standard-library construction uses synthetic values; its checks are not provider measurements.

def next_action(status, method, key=None, idempotency_supported=False):
    if status == 401:
        return "stop_auth"
    if status in {429, 503}:
        safe_replay = method == "GET" or (key is not None and idempotency_supported)
        return "retry" if safe_replay else "reconcile"
    return "validate" if status == 200 else "stop"
assert next_action(503, "GET") == "retry"
assert next_action(503, "POST") == "reconcile"
assert next_action(503, "POST", key="case-1") == "reconcile"
assert next_action(503, "POST", key="case-1", idempotency_supported=True) == "retry"
assert next_action(401, "GET") == "stop_auth"
print("retry classification passed")

The Boolean represents a separately verified server contract for this constructed exercise. Sending an arbitrary idempotency header is insufficient: the server must enforce replay identity, scope and retention for that operation. This classifier does not implement deadlines, backoff or durable recovery.

Engineering decisions

• Classify errors as retryable, non-retryable, or indeterminate.
• Set timeout, attempt, and total-time budgets.
• Choose a structured error that helps operations without exposing the request body.

Worked example

A mock service returns 429, 503, malformed JSON, and 401 in sequence. The client retries the first two within a three-attempt budget, rejects malformed JSON as a contract error, and stops immediately on 401. Logs contain request ID, outcome class, attempt, and elapsed time - not tokens or bodies.

Diagnose the failure

Unprotected writes cannot automatically retry. An excessive wait exhausts the deadline. Log attempts and status, never secret-bearing bodies; if attempts exceed the cap, repair the guard.

Part 2 Guided practice

Trace GET 503 then 200 and POST 503 without a key. Add a fake clock, three-attempt cap and total deadline. Independently test a Retry-After longer than the remaining deadline.

Answer criteria and feedback: Unprotected writes cannot automatically retry. An excessive wait exhausts the deadline. Log attempts and status, never secret-bearing bodies; if attempts exceed the cap, repair the guard.

Continue with the downloadable pack below. If the pack or interpreter is unavailable, trace this self-contained example by hand in an input/expected-status/controlling-rule table and label execution unverified. Do not invent passing output. No account, credential, paid call, purchase or actual deployment is required.

Part 3 Remediation

Use the deterministic fault sequence. If a test hangs, inspect the total-time budget and sleep abstraction. Replace real waits with the injected fake clock. After repair, reassess with the alternate scenario in scenario_alt.json. A critical authorization, data-handling, evidence-integrity, or prohibited-action failure cannot be averaged into successful practice; it requires targeted remediation.

Part 4 Sources and currency

• https://www.rfc-editor.org/rfc/rfc9110
• https://owasp.org/API-Security/

Use the workflow decision reference for model/deployment/harness distinctions and controlled comparisons. Source currency must be checked before each cohort. Provider/product behavior is illustrative where mocked; resolve current interfaces only from official documentation in an authorized environment.