Fehler und Grenzen

Flexie antwortet mit gewöhnlichen HTTP-Statuscodes und einem JSON-Rumpf, der beschreibt, was schiefgelaufen ist. Werten Sie zuerst den Status aus und lesen Sie den Rumpf, wenn Sie das Detail brauchen.

Statuscodes

Code	Bedeutung	Typische Ursache
200	Erledigt	ein Lesevorgang oder eine Aktualisierung
201	Angelegt	ein erfolgreiches POST auf /new
204	Erledigt, nichts zurückzugeben	ein erfolgreiches DELETE
400	Die Anfrage war fehlerhaft aufgebaut	ungültiges JSON oder ein Wert, den ein Feld nicht annimmt
401	Nicht authentifiziert	fehlende, falsche oder abgeschaltete Zugangsberechtigung
403	Authentifiziert, aber nicht erlaubt	der Rolle fehlt der API-Zugriff oder das Recht am Datensatz
404	So etwas gibt es nicht	unbekannte Id, unbekannte Route oder gar keine Zugangsberechtigung gesendet
405	Falsches Verb für diesen Pfad	zum Beispiel DELETE auf einer Sammlung
429	Zu viele Anfragen	Ratenbegrenzung
500	Auf unserer Seite ist etwas kaputtgegangen	eine Meldung wert

Der Aufbau eines Fehlers

Die meisten Fehler kommen als error-Objekt zurück:

{ "error": { "code": 404, "message": "Item was not found." } }

Ein Routing-Fehler nennt die Verben, die der Pfad annimmt, was die Lösung meist sofort verrät:

{ "error": { "message": "No route found for \"DELETE /api/leads\": Method Not Allowed (Allow: GET, POST, HEAD)", "code": 0 } }

Fehlgeschlagene Authentifizierungen nutzen stattdessen die flache Form im OAuth-Stil, mit einem maschinenlesbaren Code und einem Satz für Menschen:

{ "error": "api_key_disabled",
  "error_description": "This API key is disabled because an active OAuth client with the api scope exists for this user. …" }

Behandeln Sie also beides: Lesen Sie error.message, wenn error ein Objekt ist, und error_description, wenn es eine Zeichenkette ist. Die Seite Authentifizierung führt jeden Authentifizierungscode auf und was jeweils zu tun ist.

Grenzen

100 Datensätze pro Anfrage. limit wird serverseitig gedeckelt. Fordern Sie 500 an, bekommen Sie 100, mit der echten total im Umschlag, damit Sie wissen, dass es weitergeht:

{ "total": "10699", "leads": [ /* 100 */ ] }

Blättern Sie den Rest mit start bei einer Liste oder mit page bei einer Suche durch. Ein limit von 0 bedeutet ebenfalls „so viele, wie ihr erlaubt", liefert also auch 100, und alles unterhalb von null genauso. Lassen Sie limit ganz weg, bekommen Sie die Standard-Seitengröße des Arbeitsbereichs.

Ratenbegrenzung. Anfragen sind pro Arbeitsbereich begrenzt, und wer darüber liegt, bekommt 429. Warten Sie ab und versuchen Sie es erneut, statt zu hämmern; eine kurze exponentiell wachsende Wartezeit genügt. Braucht eine berechtigte Integration eine höhere Obergrenze, fragen Sie den Support, es ist eine Einstellung pro Arbeitsbereich.

Seien Sie sparsam mit der Seitengröße. 100 Datensätze mit je Dutzenden benutzerdefinierter Felder ergeben eine große Antwort. Wenn Sie nur wenige Felder brauchen, ist eine kleinere Seite unterm Strich meist schneller.

Häufige Fälle

Die meisten Supportanfragen zur API laufen auf einen der folgenden Punkte hinaus.

Filter bei einem GET werden ignoriert

Filtern ist ein POST auf /search. Ein GET liest keinen Anfragerumpf, Filter an GET /api/leads zu senden liefert also eine ungefilterte Liste und ein 200, eine erfolgreiche Antwort auf eine Frage, die Sie nicht gestellt haben. Senden Sie sie stattdessen als POST /api/leads/search. Siehe Datensätze finden.

Sie bekommen ein 404 und eine HTML-Seite statt JSON

Liefert ein Aufruf 404 mit einer HTML-Seite statt JSON, hat die Anfrage Flexie wahrscheinlich nie erreicht. Anfragen an /api müssen entweder einen apikey-Header (oder ?apikey=) oder einen Authorization: Bearer-Header mitführen; alles andere wird am Proxy abgewiesen.

Prüfen Sie, ob Ihr HTTP-Client den Header tatsächlich sendet: Einige Clients verwerfen eigene Header, wenn sie einer Weiterleitung folgen, eine http://-URL, die auf https:// weiterleitet, kann Ihren Schlüssel also stillschweigend verlieren. Rufen Sie immer direkt die https://-Adresse auf.

Der Header muss exakt apikey heißen

Klein geschrieben, ein Wort. X-Api-Key, Api-Key und ApiKey werden nicht erkannt, und die Anfrage gilt als solche ohne Zugangsberechtigung.

Senden Sie niemals beide Zugangsberechtigungen

Eine Anfrage mit einem Authorization: Bearer-Header gilt als OAuth-Anfrage, und Ihr API-Schlüssel wird nicht herangezogen. Senden Sie das eine oder das andere.

Ihr Schlüssel funktioniert über Nacht nicht mehr

Gibt ein Schlüssel, der gestern noch lief, api_key_disabled zurück, hat jemand für diesen Benutzer einen OAuth-API-Client angelegt, was den Schlüssel per Entwurf abschaltet. Ziehen Sie die Integration entweder auf OAuth um oder schalten Sie diesen Client auf dem Reiter API-Einstellungen des Benutzers ab, um den Schlüssel zurückzuholen. Siehe Authentifizierung.

edit legt nichts an

PATCH /api/leads/edit gleicht über ein eindeutiges Feld ab und gibt 404 zurück, wenn nichts passt. Es legt nie etwas an. Weichen Sie bei einem 404 auf POST /api/leads/new aus, wenn Sie ein Anlegen-oder-Aktualisieren-Verhalten wollen.

Sortieren Sie, wenn Sie blättern

Ohne ausdrückliches orderBy garantiert nichts eine stabile Reihenfolge zwischen zwei Anfragen, ein Datensatz kann also auf zwei Seiten auftauchen oder ganz übersprungen werden. Nach id zu sortieren ist die günstigste Lösung.

total ist eine Zeichenkette

Es kommt als "10699" zurück, nicht als 10699. Wandeln Sie den Wert um, bevor Sie vergleichen oder addieren.

Hilfe bekommen

Wenn wirklich etwas nicht stimmt, sind das die nützlichen Angaben:

• die vollständige URL und das Verb
• der Statuscode, den Sie bekommen haben
• der Antwortrumpf (ohne jeden Schlüssel und ohne jedes Token)
• ungefähr wann es passiert ist, damit es in den Protokollen auffindbar ist

Fügen Sie niemals einen API-Schlüssel oder ein OAuth-Token in eine Supportnachricht, ein Ticket oder einen Screenshot ein. Ist doch einmal einer versehentlich geteilt worden, erzeugen Sie den Schlüssel sofort neu oder löschen Sie den OAuth-Client.