flexport-common-errors
/flexport-common-errors
Klasyfikuje błędy REST, OAuth, webhooków i MCP we Flexport na bezpieczne działania operatora, w tym błędy uprawnień, walidacji i niejednoznaczne mutacje.
- Autor
- jeremylongshore ↗
- Repozytorium
- tons-of-skills-marketplace ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 26.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 2
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 5
Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Klasyfikuje błędy REST, OAuth, webhooków i MCP we Flexport na bezpieczne działania operatora, w tym błędy uprawnień, walidacji i niejednoznaczne mutacje.
Wyzwalacze z opisu
Argumenty
/flexport-common-errors [redacted-failure-receipt]
Oryginalny opis (EN)
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".
Jak działa
- Overview
- Prerequisites
- Instructions
- Authentication
- Tool Discipline
- Output
- Examples
- Error Handling
- Resources
Podgląd SKILL.md
--- name: flexport-common-errors description: >- 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". allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[redacted-failure-receipt]' model: inherit effort: high license: MIT author: Jeremy Longshore <jeremy@intentsolutions.io> tags: - saas - flexport - errors - operations compatibility: 'Requires a redacted response receipt with surface, operation, HTTP or JSON-RPC status, and correlation metadata.' --- # 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. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change. ## Output - Scoped decision or implementation artifact - Redacted operation and validation receipt - Failure, rollback, and follow-up ownership record Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it: ```yaml surface: rest-v3 operation: shipment-read decision: approved outcome: verified evidence: release_sha: recorded-out-of-band provider_reference: redacted rollback_owner: logistics-platform ``` ## Examples A document upload returns 422 with a provider message. The operator preserves the code/message, fixes the source document metadata, and submits a new approved operation rather than repeatedly sending the unchanged payload. ## Error Handling | Failure | Response | | --- | --- | | 401 persists after one cached-token refresh | Stop and inspect credential revocation, audience, and secret source. | | 403 on one endpoint | Verify OAuth endpoint resources or MCP role permission; do not broaden silently. | | 404 on `/tools/...` | Use the real MCP JSON-RPC endpoint rather than the synthetic docs path. | | Timeout after mutation | Reconcile using known references before any retry. | ## Resources - [First-party source notes](references/official-docs.md) - [Flexport v3 API reference](https://apidocs.flexport.com/v3/) - [API credential FAQ](https://developers.flexport.com/faq/api-credentials/) - [MCP tools](https://apidocs.flexport.com/v3/tag/MCP-Tools/)
Pliki w paczce (2)
- SKILL.md 4 KB
- references/official-docs.md 1 KB
Wersje
W bazie nie ma innych skilli o nazwie flexport-common-errors.
Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.
Migawka bazy z 13.11.2026 · wersja paczki 58648c70debf (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100flexport-debug-bundle
Zbiera pakiet diagnostyczny Flexport zawierający wyłącznie metadane, bez plików środowiskowych, logów i danych, do eskalacji defektów API, MCP, OAuth lub webhooków. - 100flexport-reference-architecture
Projektuje i analizuje architekturę integracji Flexport rozdzielającą zasoby REST v3, narzędzia MCP, wejście webhooków, zatwierdzanie i uzgadnianie, w tym model zagrożeń i granice usług. - 100flexport-webhooks
Odbiera i weryfikuje webhooki Flexport, w tym podpis X-Hub-Signature-256 i zdarzenia logistyczne takie jak /shipment#created i /shipment_leg#departed. - 100linear-common-errors
Diagnozuje i naprawia typowe błędy API Linear, w tym problemy z uwierzytelnianiem, przydatne przy debugowaniu integracji. - 100customerio-common-errors
Diagnozuje i naprawia typowe błędy Customer.io w API, dostarczaniu wiadomości i integracjach.