Agent skill · data analytics · jeremylongshore
flexport-common-errors
Classify Flexport REST, OAuth, webhook, and MCP failures into safe operator actions. Use when triaging status/code/message errors, permission failures, validation problems, or ambiguous mutations. Trigger with: "debug Flexport error", "Flexport 422", "Flexport permission denied".
Why this skill is useful
Provides specific diagnostic scripts and error handling patterns for the Flexport API that the AI wouldn't reliably generate on its own.
What it needs
Requires jq installed locally. Requires flexport account access. About 2k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Flexport Failure Classification Overview Do not convert every failure into a retry. First identify the surface and operation class, then distinguish authentication, authorization, validation, provider availability, and ambiguous mutation outcomes. Prerequisites Redacted surface and operation name HTTP status or JSON-RPC error plus documented provider code/message Knowledge of whether the failed operation could mutate freight or trade records Instructions Step 1: Identify the surface Label OAuth token, REST v3, MCP JSON-RPC, or webhook delivery; each has different failure semantics. Step 2: Protect evidence Capture timestamp, credential alias, version header, operation digest, status/code/message, and provider correlation metadata without payloads or secrets. Step 3: Classify deterministically Separate 401 authentication, 403 permission/scope, 404 resource or route, 400/422 request validation, throttling evidence, and 5xx/transport uncertainty. Step 4: Choose retry eligibility Retry only transient, idempotent work with bounded backoff. Never retry a create or booking until its prior outcome is reconciled. Step 5: Correct the owner Route credential issues to credential owners, schema issues to integration owners, business validation to data owners, and provider incidents to support. Step 6: Close with a proof Record the corrected contract or recovered result and add a regression fixture when the defect was local. Authentication REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions. Tool Discipline Use Read and Grep for discovery and evidence. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/flexport-common-errors