Best Practices

Sicherheit

• HTTPS only – Sende Requests ausschließlich über TLS.
• Secrets schützen – Leg secret_key und encryption_key nicht im Quellcode, in URLs oder in Logs ab. Auch die message ist verschlüsselt – Klartext-Parameter gehören nicht in Logdateien.
• Uhrzeit synchronisieren – Signierte Nachrichten sind nur 5 Minuten gültig; halte die Systemzeit per NTP aktuell.
• Eindeutige IDs – hmac_unique muss pro Request eindeutig sein (z. B. UUID oder Request-ID) – Wiederverwendung führt zu 403.
• Fair nutzen – Halte dich an das Rate Limit und an deinen Vertrag, siehe Zugang & Nutzungsregeln.
• Origin konfigurieren – Halte den freigegebenen Origin aktuell und melde Domain-Wechsel vorab.

Timeouts & Retries

• Setze clientseitige Timeouts (empfohlen: 30 s für normale Requests; die API bricht serverseitig nach 120 s ab).
• Wiederhole Requests nur bei 500, 502, 503 und Netzwerkfehlern – mit exponentiellem Backoff:

Versuch 1 → fehlgeschlagen → 1 s warten
Versuch 2 → fehlgeschlagen → 2 s warten
Versuch 3 → fehlgeschlagen → 4 s warten
Versuch 4 → abbrechen, Fehler melden

• 4xx-Fehler (403, 404, 406) wiederholst du nicht automatisch – der Request ist fachlich falsch oder unberechtigt.

Effizienz

• Rate Limit beachten – max. 250 Requests/s pro IP; bündele Abfragen, wenn möglich.
• Nur benötigte Daten anfragen – nutze die Filter- und Parameter-Möglichkeiten der Endpunkte, statt clientseitig zu filtern.
• Content-Type passend setzen – bei multipart/form-data (wie in den Beispielen) setzt der HTTP-Client den Header samt Boundary selbst; nur wenn der Umschlag als JSON gesendet wird, Content-Type: application/json setzen.

Robustheit

• Behandle die Response-Struktur defensiv: erfolgreiche Aktionen ohne Payload liefern [true].
• Beachte den Sonderfall 302 – manche Endpunkte antworten mit Redirect statt JSON.
• Verlass dich nicht auf die Reihenfolge von JSON-Feldern; neue Felder können ohne Vorankündigung ergänzt werden.
• Logge Request-Zeitpunkte und Statuscodes – das erleichtert die Fehlersuche mit dem Support. Bei einer Support-Anfrage gib bitte Zeitpunkt, Endpunkt, Statuscode und die verwendete hmac_unique an (keine Schlüssel und keine Klartext-Inhalte).