Error Code 104 on a POST Request for zephyr squad api

by

Summary

Error Code 104 occurred during a POST request to the Zephyr Squad API’s traceability export endpoint. Despite a valid JWT token and proper authentication headers, the API returned a vague error message: “we encountered a problem during processing this request. Please try again.” This error prevented traceability report generation for requirement ID 681391.

Root Cause

  • Invalid payload structure: The API likely expects requirementIdList as integers, but the code sends strings ([str(r) for r in requirement_ids]).
  • Mismatched export type: The export_type="excel" might not be supported by the current API version or server configuration.
  • Server-side validation failure: The API might perform strict checks on allowed parameters or data types not documented publicly.
  • Encoding/serialization issues: json.dumps(payload) could introduce unexpected formatting if payload structure deviates slightly.

Why This Happens in Real Systems

  • API version drift: The endpoint may have changed behavior (e.g., required requirementIdList format updated).
  • Incomplete documentation: The API docs might not reflect all validation rules (e.g., allowed data types).
  • Network instability: Temporary issues like timeouts or partial data transmission could trigger this error.
  • Security middleware interference: Server-side rule enforcement (e.g., input sanitization, rate limiting) might falsely reject valid requests.

Real-World Impact

  • Delayed reporting: Manual export workarounds increase team workload.
  • Reduced trust: Ambiguous errors hinder debugging, leading to unnecessary troubleshooting.
  • Operational risk: Critical traceability data unavailable, impacting project audits or compliance checks.

Example or Code

# Original problematic code
payload = {
    "exportType": export_type,
    "requirementIdList": [str(r) for r in requirement_ids]  # Sends strings instead of integers
}

# Key header to verify
headers = {
    "Authorization": jwt_token,  # Valid JWT
    "zapiAccessKey": ACCESS_KEY,  # Confirmed valid
    "Content-Type": "application/json"  # Required for JSON payload
}

How Senior Engineers Fix It

  • Validate payload against ADR: Use tools like curl or Postman to replicate the request with corrected data types (e.g., requirementIdList as integers).
  • Inspect server logs: Look for granular error codes or validation failures (e.g., 400 Bad Request).
  • Test edge cases: Verify export_type against API documentation (e.g., allowed values: "excel", "pdf").
  • Use strict mode: Enable requests library strict JSON parsing or validate headers with Wireshark/Fiddler.

Why Juniors Miss It

  • Assumed headers are sufficient: Juniors might skip verifying payload semantics, focusing only on authentication.
  • Ignored data type requirements: Novices may not recognize that API fields require specific types (e.g., integers vs strings).
  • Overlooked documentation gaps: Juniors might trust public docs implicitly, missing undocumented validations.
  • No error logging: Failing to capture server responses or headers limits root-cause analysis.

Leave a Comment