Fehlerbehebung

Diagnostizieren Sie nach Symptomen. Jeder Abschnitt ordnet ein beobachtetes Verhalten seiner Ursache und Behebung zu.

Der Konstruktor wirft bereits vor der ersten Anfrage

appId- oder apiKey-Präfixfehler. Verwenden Sie die öffentliche ID und den geheimen Schlüssel in den richtigen Feldern:

const vinkius = new Vinkius({
  appId: 'vk_app_...',
  apiKey: 'vk_app_sk_...',
});

Die öffentliche App-ID muss mit vk_app_ beginnen, aber nicht mit vk_app_sk_. Der Schlüssel muss mit vk_app_sk_ beginnen.

No global fetch found. Verwenden Sie Node.js 18 oder neuer, eine Laufzeit mit globalem fetch, oder übergeben Sie eine kompatible Implementierung über die fetch-Option des Konstruktors.

Invalid externalId. Verwenden Sie die Benutzer-ID Ihrer Anwendung, keinen vk_app_user_...-Bezeichner. Er muss 1 bis 255 Zeichen lang sein und darf keine Leerzeichen, / oder Backslashes enthalten.

Anfragen werfen AuthError

Ein HTTP-401 oder 403 wird auf AuthError abgebildet.

1. Stellen Sie sicher, dass die Umgebungsvariablen im Serverprozess geladen wurden.
2. Stellen Sie sicher, dass der Application Key zur konfigurierten App-ID und Umgebung gehört.
3. Ersetzen Sie einen widerrufenen oder rotierten Schlüssel.
4. Prüfen Sie, ob der Deployment-Code App-ID und Schlüssel vertauscht hat.
5. Erfassen Sie requestId, wenn vorhanden, aber protokollieren Sie niemals den Schlüssel.

Der Connector-Status ist not_connected

Ein Handle erzeugt keine Verbindung:

const connector = vinkius.user(externalId).connector('github');
console.log(await connector.status()); // may be 'not_connected'

await connector.connect();

connect() führt die Get-or-create-Anfrage aus. credentials.status(), credentials.set(), disconnect() und connector-bezogene capabilities() werfen ConnectorNotConnectedError, solange keine Verbindung existiert.

Der Connector-Status ist needs_credentials

Lesen Sie das Katalogschema, erfassen Sie die erforderlichen Werte in Ihrem Serverablauf und schreiben Sie sie:

const schema = await connector.credentials.schema();
const state = await connector.credentials.set(values);

console.log(schema, state.configured);

schema() kann vor der Verbindung ausgeführt werden, set() nicht. Vergleichen Sie die übermittelten Schlüsselnamen mit dem Schema und prüfen Sie ValidationError.errors, wenn der Dienst sie zurückweist. Gespeicherte Werte werden nicht zurückgegeben.

Der Connector-Status ist disabled

Die Verbindung existiert, aber ihr API-Status ist nicht aktiv. Das Neuschreiben der Credentials ändert diesen Zustand möglicherweise nicht. Zeigen Sie dem Benutzer, dass die Verbindung nicht ausführen kann, prüfen Sie bei Bedarf die Verbindungsantwort über den Low-Level-Client oder ersetzen Sie die Verbindung gemäß Ihrem Anwendungsablauf.

user.capabilities() liefert eine leere Menge

Eine leere Menge ist gültig. Prüfen Sie Scope und Filter:

const user = vinkius.user(externalId);
const connectors = await user.connectors();
const capabilities = await user.capabilities({ include: ['github'] });

console.log({ connectors, count: capabilities.length });

Prüfen Sie Folgendes der Reihe nach:

1. externalId stammte aus der beabsichtigten authentifizierten Sitzung.
2. Der erwartete Slug erscheint in connectors().
3. Sein abgeleiteter Status ist ready.
4. include verwendet den genauen Slug, den der Dienst erwartet.
5. exclude hat den Connector nicht lokal entfernt.
6. Der aggregierte Endpoint hat tatsächlich Aktionen für die Verbindung zurückgegeben.

Der Client wandelt die Endpoint-Antwort um; er fügt keinen lokalen Bereitschaftsfilter hinzu.

Die Capability-Suche liefert undefined

Prüfen Sie beide Namen:

for (const capability of capabilities) {
  console.log(capability.name, capability.rawName, capability.connector);
}

Der Standard-Anzeigename trägt einen Namespace, z. B. github__create_issue. findCapability() akzeptiert den Anzeige- oder Rohnamen und liefert die erste Übereinstimmung. Wenn Rohnamen kollidieren, rufen Sie zuerst forConnector(slug) auf oder verwenden Sie den Anzeigenamen mit Namespace.

Wenn Sie namespaceCapability angegeben haben, prüfen Sie, dass seine Ausgabe den Namensvorgaben des Anbieters entspricht und eindeutig bleibt; die Adapter erzwingen beides nicht.

Ein Adapter-Dispatcher wirft Unknown capability

Übergeben Sie dasselbe Capability-Array an Konvertierung und Dispatch, und übernehmen Sie den zurückgegebenen Anzeigenamen exakt:

const tools = toOpenAITools(capabilities);
// Send tools to the model, then:
const result = await runOpenAIToolCall(capabilities, returnedCall);

Die OpenAI-, Anthropic- und Gemini-Dispatcher gleichen nur Anzeigenamen ab. Der JSON-Schema-Dispatch akzeptiert Anzeige- oder Rohnamen, mit Ersttreffer-Mehrdeutigkeit bei doppelten Rohnamen. Unbekannte Dispatch-Namen werfen ein einfaches Error, kein VinkiusError.

OpenAI-Argumente werden unerwartet zu {}

runOpenAIToolCall analysiert call.function.arguments. Leere Zeichenketten, fehlerhaftes JSON, JSON null und primitive JSON-Werte werden alle in {} umgewandelt. Validieren oder protokollieren Sie die analysierte Struktur in Ihrer eigenen Modellschleife, wenn fehlerhafte Argumente abgelehnt statt toleriert werden sollen.

Die Ausführung wird mit isError: true aufgelöst

Die HTTP-Anfrage wurde abgeschlossen, und die Capability meldete eine fehlgeschlagene Aktion. Prüfen Sie den zurückgegebenen Inhalt:

const result = await capability.execute(args, options);

if (result.isError) {
  console.error(result.content.map((part) => part.text).join('\n'));
}

Erwarten Sie diesen Zweig nicht in catch. Eine Provider-Schleife kann das Ergebnis an das Modell zurückgeben, während eine deterministische Route es auf eine Anwendungsfehlerantwort abbilden kann. Factory-Adapter, die Zeichenketten zurückgeben, verwerfen isError; führen Sie die ursprüngliche Capability daher direkt aus, wenn diese Unterscheidung wichtig ist.

Die Ausführung ist abgelaufen oder hat ConnectionError geworfen

Lesezugriffe und andere wiederholbare Operationen können automatisch wiederholt werden. Die Capability-Ausführung wird nur wiederholt, wenn idempotencyKey nicht undefined ist:

if (!operationId) throw new Error('operationId is required');

await capability.execute(args, {
  idempotencyKey: `create-issue:${operationId}`,
});

Übergeben Sie keinen leeren Schlüssel: Die aktuelle Implementierung kann ihn als wiederholbar einstufen, ohne den Header zu senden. Nach einem Timeout ohne gültigen Schlüssel kann die externe Aktion bereits abgeschlossen sein; stimmen Sie sie ab, bevor Sie eine neue Operation senden. Adapter-Dispatch-Helfer können weder einen Idempotency-Schlüssel noch ein Signal übergeben; verwenden Sie die direkte Ausführung für Nebeneffekte, die diese Kontrollen benötigen.

Ein Rate- oder Planfehler bleibt bestehen

• RateLimitError kann nach Abschluss der automatischen Wiederholungen retryAfterMs liefern.
• QuotaError und OverageError können upgradeUrl liefern; unverändertes Wiederholen ändert kein Planlimit.
• Der Transport behandelt 429 als vorübergehend, bevor er den Body abbildet, sodass wiederholbare Anfragen Wiederholungen verbrauchen können, bevor ein endgültiger Quotenfehler auftritt.

Hooks zeigen keinen Netzwerkfehler

onResponse wird erst nach einer HTTP-Antwort ausgeführt. Ein Timeout oder Netzwerkfehler ohne Antwort ruft ihn nicht auf. onRequest wird vor jedem Versuch ausgeführt, daher kann ein Anfragelog ohne Antwortlog auf einen Transportfehler hinweisen. Hook-Ausnahmen werden als ihre ursprünglichen Werte weitergegeben; halten Sie Hooks frei von Ausnahmen. Das SDK schwärzt eine feste Liste exakter Feldnamen, nicht jeden benutzerdefinierten Schlüssel mit Secret-Form.

Diagnosedaten für den Support erfassen

import { VinkiusError } from '@vinkius/connect';

if (error instanceof VinkiusError) {
  console.error({
    code: error.code,
    status: error.status,
    requestId: error.requestId,
    connector: connector.slug,
    occurredAt: new Date().toISOString(),
  });
}

Ein lokaler oder Transportfehler hat möglicherweise kein requestId. Fügen Sie keine Anwendungsschlüssel, Credential-Werte, Authorization-Header oder ungeprüfte error.details hinzu. Melden Sie Sicherheitsprobleme privat an security@vinkius.com; siehe Security.

Nächste Schritte

• Review the error taxonomy
• Understand what the platform guarantees
• Run the quickstart against your environment