dojo.md 0.1.0 → 0.2.0

package/courses/GENERATION_LOG.md

@@ -441,3 +441,30 @@ Tracks all auto-generated courses for dojo.md.
 - **Scenarios**: 50 (10 per level × 5 levels)
 - **Type**: output
 - **Sources**: GitHub Issues documentation, GitHub Projects documentation, GitHub Security Advisories (GHSA), GitHub Issue Metrics Action, Kubernetes issue triage guidelines, Probot stale bot, actions/stale, GitHub issue forms YAML syntax, GDPR data privacy regulations, SOC 2 trust service criteria, EU Accessibility Act (2025), DORA (Digital Operational Resilience Act), SEC cybersecurity disclosure rules, behavioral science research (completion bias, familiarity bias, decision fatigue)
+
+### Course 45: GitHub PR Review Comments (`github-pr-review`)
+- **Generated**: 2026-02-27
+- **Category**: Development & DevOps
+- **Directory**: `courses/github-pr-review/`
+- **Topics researched**: PR review comment types (line comments, file-level comments, review summaries), review states (approve, request changes, comment), review etiquette and constructive feedback, PR review checklists (correctness, security, performance, style), PR template design (description, testing, checklist), CODEOWNERS configuration and review routing, test coverage review (quality vs quantity, edge cases, meaningful assertions), PR scope and size evaluation (splitting strategies, dependency chains), review summary writing (decision-leading, contextualizing, actionable), security-focused review (OWASP Top 10, SQL injection, XSS, auth bypass), performance review patterns (N+1 queries, memory leaks, render cycles), automated review tooling (ESLint, Prettier, CodeQL, danger.js, CI integration), review metrics analysis (turnaround time, reviewer load, comment categories), stacked PR review (dependent chains, merge order, cross-PR issues), review turnaround SLAs (tiered targets, escalation, fairness), cross-team review (non-expert review, API contracts, organizational patterns), review disagreement resolution (architecture disputes, style wars, testing philosophy), API change review (backward compatibility, versioning, migration), large-scale review operations (100+ engineer processes, knowledge distribution), review culture design (psychological safety, toxic pattern intervention, training), AI-powered code review (tool evaluation, human-AI boundaries, change management), monorepo review process (CODEOWNERS, CI optimization, cross-package), compliance-aware review (SOX, SOC 2, PCI DSS, audit trails, emergency changes), review data pipeline (analytics architecture, privacy, metrics), cross-functional review (design, security, legal, product stakeholders), incident-driven review improvement (post-incident analysis, systemic fixes), review automation platform (GitHub Apps, assignment algorithms, categorization), enterprise review operations (multi-BU standardization, migration), review platform architecture (scalability, reliability, deployment), review economics and ROI (cost modeling, investment analysis, executive presentation), review org design (team structure, career paths, interaction models), review vendor evaluation (TCO analysis, security assessment, pilot programs), review incident postmortem (blameless analysis, multi-level improvements), executive communication (board updates, CEO memos, all-hands), reviewer training programs (curriculum, shadow reviewing, certification), review data architecture (ML feature store, analytics layer, privacy), consulting engagements (16-week transformation, diagnostic, handoff), industry benchmarks (cross-industry analysis, methodology, predictions), board-level strategy (risk governance, AI strategy, M&A due diligence), AI future of review (product vision, ethical framework, go-to-market), M&A review integration (culture harmonization, retention risk), behavioral science (cognitive biases, nudge interventions, A/B testing), DevTools product (SaaS startup, pricing, PLG), comprehensive review systems (5-layer Fortune 500 architecture), regulatory landscape (EU AI Act, SEC, DORA, PIPL, Software Liability Act), master crisis management (SEC investigation, competitive disruption, platform outage, talent exodus, board pressure)
+- **Scenarios**: 50 (10 per level × 5 levels)
+- **Type**: output
+- **Sources**: GitHub Pull Request documentation, CODEOWNERS syntax, GitHub branch protection rules, GitHub rulesets, OWASP Top 10 (2021), CodeQL documentation, ESLint configuration, Prettier configuration, danger.js API, SOC 2 trust service criteria (CC8.1), PCI DSS Requirement 6.5, SOX change management controls, EU AI Act (2024), SEC cybersecurity disclosure rules, DORA (Digital Operational Resilience Act), India DPDP Act, China PIPL, behavioral economics research (authority bias, anchoring effect, social loafing, sunk cost fallacy)
+
+### Course 46: GitHub Actions CI/CD Setup (`github-actions-cicd`)
+- **Generated**: 2026-02-27
+- **Category**: Development & DevOps
+- **Directory**: `courses/github-actions-cicd/`
+- **Topics researched**: Basic workflow YAML syntax (name, on, jobs, steps, runs-on), workflow triggers (push, pull_request, schedule, workflow_dispatch, release, path filters), actions and runners (marketplace actions, service containers, GitHub-hosted vs self-hosted, resource limits), environment variables and secrets (repository/environment/organization scopes, masking, fork security), simple CI pipelines (lint/test/build, job dependencies, caching), job dependencies and outputs ($GITHUB_OUTPUT, needs, conditional execution with status functions), workflow debugging (common errors, debug logging, act tool), branch protection with status checks (required reviews, required checks, admin bypass), workflow notifications (status badges, Slack alerts, PR comment updates), matrix builds (include/exclude, fail-fast, continue-on-error, cost optimization), dependency caching (actions/cache, built-in cache, cross-branch sharing, Docker layer caching), conditional execution (if expressions, context variables, error recovery patterns), reusable workflows (workflow_call, composite actions, workflow templates, DRY patterns), deployment workflows (staging/production, GitHub Environments, approval gates, rollback), concurrency control (concurrency groups, cancel-in-progress, merge queues), GitHub Packages publishing (npm, Docker GHCR, multi-arch builds, provenance), workflow cost optimization (billing analysis, path filters, runner economics), custom actions development (JavaScript/Docker/composite actions, testing, publishing), self-hosted runners (ARC, Kubernetes, security hardening, auto-scaling, cost analysis), security hardening (supply chain attacks, SHA pinning, GITHUB_TOKEN permissions, OIDC, script injection, pull_request_target), monorepo CI (change detection, dynamic matrix, Turborepo integration, selective testing), OIDC cloud deployments (AWS/GCP/Azure keyless auth, trust policies, migration), release automation (semantic versioning, changelog generation, semantic-release vs release-please vs changesets, artifact signing), workflow optimization (parallelism, test sharding, runner sizing), GitHub Environments (protection rules, deployment gates, canary deployments, ephemeral environments), Docker action development (multi-stage builds, compliance scanners, SARIF integration), compliance automation (SOC 2/PCI DSS/HIPAA controls, required workflows, evidence collection), enterprise CI/CD governance (policy-as-code, action allowlisting, organization rulesets), CI/CD vendor evaluation (GitHub Actions vs GitLab CI vs CircleCI vs Jenkins, TCO analysis), CI/CD platform architecture (runner fleet, auto-scaling, observability, disaster recovery), CI/CD economics and ROI (hidden costs, DORA metrics, investment analysis), CI/CD incident response (platform outages, credential leaks, deployment corruption), CI/CD org design (platform engineering teams, service catalogs, career paths), executive communication (board presentations, CFO reviews, DORA metrics, all-hands), CI/CD data architecture (analytics pipelines, DORA computation, ML failure prediction), CI/CD training programs (tiered curriculum, sandbox environments, certification), consulting engagements (12-week transformation, HIPAA compliance, handoff packages), industry benchmarks (DORA metrics by size/industry, market share, predictions), board strategy (competitive intelligence, $15M investment case, M&A assessment), AI future of CI/CD (predictive CI, self-healing pipelines, natural language workflows), M&A integration (multi-platform consolidation, compliance harmonization, ML pipeline migration), behavioral science (learned helplessness, present bias, choice overload, nudge design), comprehensive CI/CD systems (5-layer Fortune 500 architecture, 8 BU integration), regulatory landscape (EU CRA, SLSA, SBOM, SEC, NIST SSDF, AI Act), master crisis management (supply chain attack, SEC enforcement, vendor risk, talent exodus, board emergency)
+- **Scenarios**: 50 (10 per level × 5 levels)
+- **Type**: output
+- **Sources**: GitHub Actions documentation, GitHub Actions workflow syntax, GitHub Environments documentation, GitHub OIDC documentation, GitHub Packages documentation, actions-runner-controller (ARC), DORA metrics (Accelerate State of DevOps), SLSA framework, Sigstore/cosign, OpenSSF Scorecard, NIST SSDF, EU Cyber Resilience Act, SOC 2 trust service criteria, PCI DSS requirements, HIPAA Security Rule, SEC cybersecurity disclosure rules, Turborepo documentation, semantic-release, release-please, changesets
+
+### Course 47: REST API Error Handling (`rest-api-error-handling`)
+- **Generated**: 2026-02-27
+- **Category**: Development & DevOps
+- **Directory**: `courses/rest-api-error-handling/`
+- **Topics researched**: HTTP status codes (2xx/4xx/5xx families, correct selection per scenario), error response format design (consistent JSON structure, field-level validation errors), request validation errors (collect-all-errors approach, unknown field handling, format validation), authentication errors (401 vs 403, information leakage prevention, security-first error messages), 5xx server error handling (global error handler, stack trace prevention, correlation IDs), rate limiting errors (429 with headers, X-RateLimit-*, Retry-After, burst allowance), not-found error taxonomy (404 vs 410 vs 403, decision trees for missing resources), error logging (structured JSON, PII masking, correlation ID flow), content negotiation errors (415, 406, Content-Type/Accept handling), RFC 7807 Problem Details (type URIs, extensions, migration), retry and idempotency (idempotency keys, retryable status codes, exponential backoff with jitter), circuit breaker pattern (closed/open/half-open states, fallback strategies, criticality-based thresholds), error monitoring and alerting (alert taxonomy, noise reduction, anomaly detection), pagination errors (cursor vs offset, edge cases, consistency), webhook error handling (retry policies, dead letter queues, delivery monitoring), batch request errors (partial success, 207 Multi-Status, transaction vs partial semantics), API versioning errors (deprecation headers, sunset, migration hints), error code taxonomy (hierarchical naming, governance, SDK integration), distributed error propagation (service chain context, translation rules, OpenTelemetry), error budgets and SRE (SLI/SLO/SLA, budget calculation, burn rate alerting), API gateway error handling (gateway vs backend distinction, format normalization, partial failure aggregation), database error handling (PostgreSQL error code mapping, constraint translation, read replica lag), async API errors (sync vs deferred validation, job failure format, callback retry), GraphQL vs REST errors (dual-protocol strategy, error extensions, monitoring when status is always 200), chaos engineering for APIs (fault injection experiments, safety guardrails, progressive rollout), error correlation (root cause identification, alert deduplication, dependency graph analysis), caching error scenarios (stampede protection, stale data, cache poisoning, negative caching), enterprise error governance (standardization at scale, automated enforcement, adoption strategy), error analytics platform (data architecture, anomaly detection, business impact calculation), compliance error handling (PCI DSS + HIPAA + GDPR + SOC 2 unified framework, PII in logs remediation), error SLA design (metrics definition, penalty structure, anti-gaming provisions), error handling architecture (4-layer Fortune 500 design, multi-region, multi-cloud), error cost optimization ($8.5M → $4.25M reduction, ROI-prioritized initiatives), executive communication (board presentations, DORA-to-business translation), error org design (centralized vs embedded vs hybrid SRE models), error training programs (tiered curriculum, sandbox exercises, certification), consulting engagements (12-week transformation, quick wins, sustainable handoff), industry benchmarks (maturity model, cross-industry comparison, predictions), board strategy ($15M investment case, NPV, competitor positioning), AI-powered error handling (prediction, auto-remediation, safety framework, ethics), M&A integration (dual-platform unification, compliance harmonization, change management), behavioral science (anchoring, learned helplessness, A/B testing error messages), error handling product development (SaaS MVP, pricing, go-to-market), comprehensive error systems (5-layer Fortune 500 architecture, multi-protocol), regulatory landscape (GDPR, PCI DSS, HIPAA, DORA, DPDP Act, conflict resolution), master crisis management (zero-day in error middleware, GDPR investigation, customer litigation, talent exodus, board emergency)
+- **Scenarios**: 50 (10 per level × 5 levels)
+- **Type**: output
+- **Sources**: RFC 7807 (Problem Details for HTTP APIs), RFC 9457, RFC 8594 (Sunset header), RFC 5322 (email format), HTTP status code specifications, Google SRE handbook (error budgets, SLOs), OpenTelemetry distributed tracing documentation, GDPR Articles 5/17/30/33/44, PCI DSS v4.0 Requirements 3.4/10.2/10.5/10.6, HIPAA Security Rule, SOC 2 trust service criteria, EU DORA (Digital Operational Resilience Act), India DPDP Act, EU AI Act, SEC cybersecurity disclosure rules, NIST 800-53, Stripe API error handling documentation, Sentry error tracking, Datadog monitoring, PagerDuty incident management, behavioral economics research (anchoring effect, learned helplessness, completion bias, loss aversion, social proof)

package/courses/api-error-handling/course.yaml

@@ -0,0 +1,16 @@
+name: "API Error Handling Mastery"
+id: "api-error-handling"
+description: "Comprehensive training course on REST API error handling from fundamentals to enterprise mastery"
+version: "1.0.0"
+difficulty_levels:
+  - level-1-beginner
+  - level-2-intermediate
+  - level-3-advanced
+  - level-4-expert
+  - level-5-master
+
+meta:
+  pass_rate_required: 0.70
+  model_for_agent: "claude-haiku"
+  model_for_evaluator: "claude-haiku"
+  model_for_skill_generation: "claude-3-5-sonnet"

package/courses/api-error-handling/scenarios/level-1/error-response-format.yaml

@@ -0,0 +1,131 @@
+name: "Error Response Format and Structure"
+level: 1
+difficulty: beginner
+description: "Learn to structure consistent, meaningful error responses with proper JSON format"
+
+context: |
+  Your API needs to return consistent error responses so clients can parse and handle
+  errors programmatically. Design error response objects with status code, error code,
+  message, and request ID for tracing.
+
+scenario:
+  state:
+    products:
+      "prod_001": { name: "Laptop", price: 999.99 }
+      "prod_002": { name: "Mouse", price: 29.99 }
+
+  endpoint: "POST /api/v1/products/{productId}/order"
+
+  test_cases:
+    - name: "valid_order"
+      request:
+        path: "/api/v1/products/prod_001/order"
+        body: { quantity: 1 }
+      expected_response:
+        status: 201
+        body:
+          order_id: "order_123"
+          product_id: "prod_001"
+          quantity: 1
+
+    - name: "product_not_found_consistent_format"
+      request:
+        path: "/api/v1/products/prod_999/order"
+        body: { quantity: 1 }
+      expected_status: 404
+      expected_response:
+        status: 404
+        error:
+          code: "PRODUCT_NOT_FOUND"
+          message: "The product you requested does not exist"
+          details:
+            product_id: "prod_999"
+
+    - name: "invalid_quantity_format"
+      request:
+        path: "/api/v1/products/prod_001/order"
+        body: { quantity: "not_a_number" }
+      expected_status: 400
+      expected_response:
+        status: 400
+        error:
+          code: "INVALID_REQUEST_BODY"
+          message: "Invalid request format"
+          details:
+            field: "quantity"
+            expected_type: "number"
+            received_type: "string"
+
+    - name: "missing_required_field"
+      request:
+        path: "/api/v1/products/prod_001/order"
+        body: {}
+      expected_status: 400
+      expected_response:
+        status: 400
+        error:
+          code: "MISSING_REQUIRED_FIELD"
+          message: "Required field missing"
+          details:
+            field: "quantity"
+
+    - name: "negative_quantity"
+      request:
+        path: "/api/v1/products/prod_001/order"
+        body: { quantity: -5 }
+      expected_status: 400
+      expected_response:
+        status: 400
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Quantity must be positive"
+
+assertions:
+  - type: "api_called"
+    description: "Error responses include machine-readable error code"
+    test: "error responses always include error.code field"
+
+  - type: "api_called"
+    description: "Error responses include human-readable message"
+    test: "error responses always include error.message field"
+
+  - type: "api_called"
+    description: "Error responses are consistent in structure"
+    test: "all 4xx errors use same response envelope format"
+
+  - type: "api_called"
+    description: "Additional error details provided where helpful"
+    test: "validation errors include field information in details"
+
+  - type: "outcome"
+    description: "Consistent error format improves client error handling"
+    test: "clients can parse error responses without special cases for each endpoint"
+
+learning_objectives:
+  - "Design consistent error response envelope format"
+  - "Include error code, message, and optional details in responses"
+  - "Provide machine-readable error codes for programmatic handling"
+  - "Include request tracing information for debugging"
+  - "Document error codes in API specification"
+
+key_concepts:
+  - "Error Response Envelope: Consistent structure across all error responses"
+  - "Error Codes: Machine-readable identifiers (PRODUCT_NOT_FOUND, INVALID_REQUEST_BODY)"
+  - "Error Message: Human-readable description of the problem"
+  - "Details Field: Additional context like field name for validation errors"
+  - "Request ID: Correlation ID for request tracing"
+
+example_error_response: |
+  {
+    "status": 400,
+    "error": {
+      "code": "INVALID_REQUEST_BODY",
+      "message": "Invalid or missing required field",
+      "details": {
+        "field": "email",
+        "expected_type": "string",
+        "constraint": "valid email format"
+      }
+    },
+    "request_id": "req_abc123def456"
+  }

package/courses/api-error-handling/scenarios/level-1/http-status-codes-basics.yaml

@@ -0,0 +1,90 @@
+name: "HTTP Status Code Fundamentals"
+level: 1
+difficulty: beginner
+description: "Understand 2xx success, 4xx client error, and 5xx server error status codes"
+
+context: |
+  You're building a user authentication API endpoint. You need to return the correct
+  HTTP status codes for different scenarios: successful login, invalid credentials,
+  missing required fields, and server outages.
+
+scenario:
+  state:
+    user_database:
+      "user123@example.com": { password_hash: "hashed_pwd_123", name: "John Doe" }
+      "user456@example.com": { password_hash: "hashed_pwd_456", name: "Jane Smith" }
+    service_status: "healthy"
+
+  endpoint: "POST /api/v1/auth/login"
+
+  test_cases:
+    - name: "successful_login"
+      request:
+        body: { email: "user123@example.com", password: "correct_password" }
+      expected_status: 200
+      expected_response:
+        token: "jwt_token_here"
+        user_id: "user123@example.com"
+
+    - name: "invalid_credentials"
+      request:
+        body: { email: "user123@example.com", password: "wrong_password" }
+      expected_status: 401
+      expected_response_contains: "Unauthorized"
+
+    - name: "missing_email_field"
+      request:
+        body: { password: "some_password" }
+      expected_status: 400
+      expected_response_contains: "email is required"
+
+    - name: "malformed_email"
+      request:
+        body: { email: "not-an-email", password: "password123" }
+      expected_status: 400
+      expected_response_contains: "invalid email format"
+
+    - name: "user_not_found"
+      request:
+        body: { email: "nonexistent@example.com", password: "password" }
+      expected_status: 401
+
+    - name: "server_error_scenario"
+      request:
+        body: { email: "user123@example.com", password: "correct_password" }
+        simulate_error: "database_connection_failed"
+      expected_status: 500
+      expected_response_contains: "Internal Server Error"
+
+assertions:
+  - type: "http_status"
+    description: "2xx codes indicate successful operations"
+    test: "successful_login returns 200"
+
+  - type: "http_status"
+    description: "401 Unauthorized for authentication failures"
+    test: "invalid_credentials returns 401"
+
+  - type: "http_status"
+    description: "400 Bad Request for malformed requests"
+    test: "missing required fields returns 400"
+
+  - type: "http_status"
+    description: "400 for invalid data format"
+    test: "malformed_email returns 400"
+
+  - type: "http_status"
+    description: "5xx codes indicate server-side errors"
+    test: "database failure returns 500"
+
+learning_objectives:
+  - "Understand HTTP status code categories (2xx, 3xx, 4xx, 5xx)"
+  - "Know when to use 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 500 Internal Server Error"
+  - "Distinguish between client errors (4xx) and server errors (5xx)"
+  - "Return appropriate status codes for different error scenarios"
+
+key_concepts:
+  - "2xx Success Codes: Indicate successful request processing"
+  - "4xx Client Error Codes: Client-side issues - malformed requests, auth failures, not found"
+  - "5xx Server Error Codes: Server-side issues - database failures, unhandled exceptions"
+  - "Status code semantics matter: Never return 200 with an error message"

package/courses/api-error-handling/scenarios/level-1/rate-limiting-basics.yaml

@@ -0,0 +1,135 @@
+name: "Rate Limiting and 429 Errors"
+level: 1
+difficulty: beginner
+description: "Implement rate limiting to protect APIs and return 429 Too Many Requests errors"
+
+context: |
+  Build a rate-limited API endpoint that allows 10 requests per minute per user.
+  When the limit is exceeded, return 429 status with information about rate limit reset.
+
+scenario:
+  state:
+    rate_limits:
+      user_123: { requests_in_window: 0, window_start: "2024-01-01T00:00:00Z", limit: 10, window_seconds: 60 }
+      user_456: { requests_in_window: 10, window_start: "2024-01-01T00:00:00Z", limit: 10, window_seconds: 60 }
+      user_789: { requests_in_window: 5, window_start: "2024-01-01T00:00:30Z", limit: 10, window_seconds: 60 }
+
+  endpoint: "GET /api/v1/data/{resource_id}"
+
+  test_cases:
+    - name: "request_within_limit"
+      request:
+        path: "/api/v1/data/resource_1"
+        headers:
+          authorization: "Bearer token_user_123"
+        current_time: "2024-01-01T00:00:05Z"
+      expected_status: 200
+      expected_response_headers:
+        - "X-RateLimit-Limit: 10"
+        - "X-RateLimit-Remaining: 9"
+        - "X-RateLimit-Reset: 2024-01-01T00:01:00Z"
+
+    - name: "request_at_limit"
+      request:
+        path: "/api/v1/data/resource_1"
+        headers:
+          authorization: "Bearer token_user_456"
+        current_time: "2024-01-01T00:00:30Z"
+      expected_status: 429
+      expected_response:
+        error:
+          code: "RATE_LIMIT_EXCEEDED"
+          message: "Too many requests. Please retry after some time."
+      expected_response_headers:
+        - "X-RateLimit-Limit: 10"
+        - "X-RateLimit-Remaining: 0"
+        - "X-RateLimit-Reset: 2024-01-01T00:01:00Z"
+        - "Retry-After: 30"
+
+    - name: "request_exceeds_limit"
+      request:
+        path: "/api/v1/data/resource_1"
+        headers:
+          authorization: "Bearer token_user_456"
+        current_time: "2024-01-01T00:00:45Z"
+      expected_status: 429
+      expected_response:
+        error:
+          code: "RATE_LIMIT_EXCEEDED"
+      expected_response_headers:
+        - "Retry-After: 15"
+
+    - name: "window_reset_allows_new_requests"
+      request:
+        path: "/api/v1/data/resource_1"
+        headers:
+          authorization: "Bearer token_user_456"
+        current_time: "2024-01-01T00:01:05Z"
+      expected_status: 200
+      expected_response_headers:
+        - "X-RateLimit-Remaining: 9"
+
+    - name: "anonymous_user_lower_limit"
+      request:
+        path: "/api/v1/data/resource_1"
+        headers: {}
+        current_time: "2024-01-01T00:00:10Z"
+      expected_status: 200
+      expected_response_headers:
+        - "X-RateLimit-Limit: 5"
+
+assertions:
+  - type: "http_status"
+    description: "429 returned when rate limit exceeded"
+    test: "rate_limit_exceeded returns 429"
+
+  - type: "api_called"
+    description: "Rate limit headers included in all responses"
+    test: "X-RateLimit-Limit header present in responses"
+
+  - type: "api_called"
+    description: "Retry-After header provided in 429 response"
+    test: "429 response includes Retry-After header"
+
+  - type: "api_called"
+    description: "Rate limit reset time communicated"
+    test: "X-RateLimit-Reset header shows window reset time"
+
+  - type: "api_called"
+    description: "Remaining requests tracked"
+    test: "X-RateLimit-Remaining decrements with each request"
+
+  - type: "outcome"
+    description: "Rate limits are enforced per user"
+    test: "different users have independent rate limit windows"
+
+learning_objectives:
+  - "Understand rate limiting purpose: protect API from abuse and ensure fair usage"
+  - "Implement per-user rate limiting windows"
+  - "Return 429 Too Many Requests when limit exceeded"
+  - "Include rate limit information in response headers"
+  - "Provide Retry-After header for client backoff guidance"
+  - "Differentiate rate limits for authenticated vs anonymous users"
+  - "Reset rate limit windows at appropriate intervals"
+
+standard_headers:
+  "X-RateLimit-Limit": "Maximum requests allowed in window"
+  "X-RateLimit-Remaining": "Requests remaining in current window"
+  "X-RateLimit-Reset": "Unix timestamp or ISO 8601 when window resets"
+  "Retry-After": "Seconds to wait before retrying (429 only)"
+
+best_practices:
+  - "Include rate limit headers in all responses, not just 429"
+  - "Use consistent rate limit windows (typically 1-60 seconds)"
+  - "Consider different limits for different user tiers"
+  - "Log rate limit violations for monitoring"
+  - "Include Retry-After guidance for clients"
+  - "Reset windows in predictable intervals to avoid thundering herd"
+
+common_mistakes:
+  - "Returning 500 instead of 429 for rate limit violations"
+  - "Not including rate limit headers in responses"
+  - "Applying same limits to all user types"
+  - "Using unclear Retry-After values"
+  - "Not resetting rate limit windows"
+  - "Blocking entire IP address instead of per-user limiting"

package/courses/api-error-handling/scenarios/level-1/request-validation-errors.yaml

@@ -0,0 +1,208 @@
+name: "Request Validation Error Handling"
+level: 1
+difficulty: beginner
+description: "Handle common validation errors: missing fields, invalid types, constraint violations"
+
+context: |
+  Implement comprehensive input validation for a user registration endpoint.
+  Handle missing fields, invalid formats, constraint violations, and size limits.
+
+scenario:
+  state:
+    existing_users:
+      - email: "john@example.com"
+      - email: "jane@example.com"
+    validation_rules:
+      email: "required, valid email format, unique"
+      password: "required, minimum 8 characters"
+      name: "required, non-empty string, max 100 characters"
+      age: "optional, integer, must be 18+"
+
+  endpoint: "POST /api/v1/users/register"
+
+  test_cases:
+    - name: "valid_registration"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "New User"
+          age: 25
+      expected_status: 201
+      expected_response:
+        user_id: "user_new_123"
+        email: "newuser@example.com"
+
+    - name: "missing_email"
+      request:
+        body:
+          password: "SecurePassword123"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "MISSING_REQUIRED_FIELD"
+          details:
+            field: "email"
+
+    - name: "missing_password"
+      request:
+        body:
+          email: "newuser@example.com"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "MISSING_REQUIRED_FIELD"
+          details:
+            field: "password"
+
+    - name: "invalid_email_format"
+      request:
+        body:
+          email: "not-an-email"
+          password: "SecurePassword123"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "INVALID_EMAIL_FORMAT"
+          message: "Email must be a valid email address"
+
+    - name: "password_too_short"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "short"
+          name: "New User"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Password must be at least 8 characters"
+
+    - name: "name_exceeds_max_length"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "A" * 101
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Name must not exceed 100 characters"
+
+    - name: "empty_name"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: ""
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Name cannot be empty"
+
+    - name: "age_below_minimum"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "Young User"
+          age: 17
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Age must be 18 or older"
+
+    - name: "age_invalid_type"
+      request:
+        body:
+          email: "newuser@example.com"
+          password: "SecurePassword123"
+          name: "User"
+          age: "twenty-five"
+      expected_status: 400
+      expected_response:
+        error:
+          code: "INVALID_FIELD_TYPE"
+          details:
+            field: "age"
+            expected_type: "integer"
+            received_type: "string"
+
+    - name: "duplicate_email"
+      request:
+        body:
+          email: "john@example.com"
+          password: "SecurePassword123"
+          name: "John Copy"
+      expected_status: 409
+      expected_response:
+        error:
+          code: "EMAIL_ALREADY_EXISTS"
+          message: "An account with this email already exists"
+
+    - name: "multiple_validation_errors"
+      request:
+        body:
+          password: "short"
+          name: ""
+          age: 10
+      expected_status: 400
+      expected_response:
+        error:
+          code: "VALIDATION_ERROR"
+          message: "Multiple validation errors"
+          details:
+            errors:
+              - field: "email"
+                code: "MISSING_REQUIRED_FIELD"
+              - field: "password"
+                code: "TOO_SHORT"
+              - field: "name"
+                code: "EMPTY"
+
+assertions:
+  - type: "http_status"
+    description: "400 Bad Request for validation errors"
+    test: "all validation errors return 400 status"
+
+  - type: "api_called"
+    description: "Missing required fields identified"
+    test: "MISSING_REQUIRED_FIELD error for absent email"
+
+  - type: "api_called"
+    description: "Invalid format errors detected"
+    test: "INVALID_EMAIL_FORMAT error for malformed email"
+
+  - type: "api_called"
+    description: "Constraint violations reported"
+    test: "Password length constraint violation returns error"
+
+  - type: "http_status"
+    description: "409 Conflict for duplicate unique fields"
+    test: "duplicate email returns 409"
+
+  - type: "api_called"
+    description: "Multiple errors reported together"
+    test: "multiple validation errors returned as array"
+
+learning_objectives:
+  - "Validate required vs optional fields"
+  - "Check data type correctness before processing"
+  - "Validate format constraints (email, URL, phone number)"
+  - "Enforce business rule constraints (min/max, uniqueness)"
+  - "Report multiple validation errors together"
+  - "Use 409 Conflict for duplicate unique constraints"
+
+common_mistakes:
+  - "Failing to validate email format before storage"
+  - "Not checking for duplicate emails/unique constraints"
+  - "Accepting invalid data types without type checking"
+  - "Returning 200 OK with validation error message"
+  - "Only reporting first error instead of all validation issues"
+  - "Not providing enough detail about what validation failed"