Fehler

Jeder Fehler an jedem Endpunkt nutzt denselben Umschlag:

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

Verzweigen Sie über error.code, zeigen Sie error.message Menschen an. Bei Validierungsfehlern kommt ein details-Array mit Meldungen je Feld hinzu:

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

Fehlercodes

| Code | HTTP | Bedeutung | Was zu tun ist | |---|---|---|---| | unauthorized | 401 | Schlüssel fehlt, ist unbekannt, widerrufen oder abgelaufen | Header prüfen; neuen Schlüssel ausstellen | | forbidden | 403 | Falsche Schlüsselart für den Endpunkt, oder die Operation ist nicht erlaubt | Workspace- bzw. Partner-Schlüssel wie dokumentiert verwenden | | insufficient_scope | 403 | Dem Schlüssel fehlt eine nötige Berechtigung | Schlüssel mit der in der Meldung genannten Berechtigung anlegen | | plan_restricted | 403 | Der Tarif enthält diese Fähigkeit nicht | Tarif hochstufen oder die Funktion aus der Anfrage nehmen | | not_found | 404 | Die Ressource existiert nicht — oder gehört einem anderen Mandanten | ID prüfen; fremde Ressourcen sind von fehlenden nicht zu unterscheiden | | invalid_request | 400 | Fehlerhaftes JSON, ungültiger Cursor, verletzte Geschäftsregel | Anfrage korrigieren | | validation_failed | 422 | Rumpf oder Query haben die Schemaprüfung nicht bestanden | Die in details gelisteten Felder korrigieren | | conflict | 409 | Zustandskonflikt: vergebener Slug, wiederverwendeter Idempotency-Key mit anderem Rumpf | Anderen Wert oder frischen Idempotency-Key wählen | | quota_exceeded | 422 | Ein Tarifkontingent ist erschöpft (Links, Domains, Kunden) | Tarif hochstufen oder Kontingent freimachen | | rate_limited | 429 | Zu viele Anfragen für diesen Schlüssel | Retry-After Sekunden warten; siehe Rate-Limits | | not_configured | 503 | Die Fähigkeit ist in dieser Umgebung nicht konfiguriert | Später erneut versuchen oder den Support kontaktieren | | internal | 500/502/504 | Unerwarteter Plattformfehler | Mit Backoff wiederholen; bei Dauer melden | | invalid_click_id | 422 | Die click_id ist gefälscht, wurde verändert oder in einem anderen Workspace vergeben | Den Wert des Parameters mit der Klick-Kennung genau so übergeben, wie er in der Zieladresse stand | | attribution_expired | 422 | Der Klick ist älter als das Attributionsfenster des Workspace | Nichts zu wiederholen; das Fenster bei Bedarf im Dashboard anpassen |

Umgangsregeln, die sich auszahlen

• 404 ist auch Trennung. Eine ID aus einem anderen Workspace antwortet mit not_found, nie mit forbidden — die API verrät nicht, ob eine fremde ID existiert.
• Nur wiederholen, was gefahrlos ist. Wiederholen Sie internal und rate_limited mit Backoff. Wiederholen Sie niemals blind conflict oder validation_failed — die Anfrage selbst ist falsch. Nutzen Sie Idempotency-Key, damit verändernde Anfragen gefahrlos wiederholbar sind.
• GET /links antwortet nie mit 404. Leere Filter liefern eine leere Liste; ein 404 auf der Sammlung wäre mehrdeutig.