Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

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.

Licencja
MIT
Ostatnia zmiana repozytorium
26.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
5
Przestarzałość

Brak sygnałów. Repozytorium zmienione 26.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

debug Flexport errorFlexport 422Flexport permission denied

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

  1. Overview
  2. Prerequisites
  3. Instructions
  4. Authentication
  5. Tool Discipline
  6. Output
  7. Examples
  8. Error Handling
  9. Resources
Sekcje z nagłówków SKILL.md, w oryginale · 86 linii, 485 słów
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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.