Fehler und Limits

Die API verwendet die Standard-HTTP-Codes und liefert im Fehlerfall immer einen JSON-Body.

Format eines Fehlers#

{
  "message": "Le plafond de 5 dossiers de votre licence est atteint.",
  "code": "company_limit_reached",
  "errors": {
    "name": ["Le plafond de 5 dossiers de votre licence est atteint."]
  }
}

Einige Fehler fügen eigene Felder hinzu, zum Beispiel required_ability, server_version und server_data oder blocker_codes für Peppol.

HTTP-Codes#

Ein Mandat, das existiert, auf das Sie aber keinen Zugriff haben, antwortet mit 404 und nicht mit 403. Das ist beabsichtigt: Die API gibt die Existenz eines Mandats nicht an Unbefugte preis.

Maschinencodes#

Authentifizierung und Zugriff#

Lizenz und Obergrenzen#

Gleichzeitige Zugriffe und Verlauf#

Synchronisierung#

Diese Codes erscheinen im Ergebnis jeder Mutation von sync/push, nicht als HTTP-Status.

Peppol#

Peppol-Ablehnungen liefern blocker_codes, eine Liste aus: provider_not_configured, vat_number_missing, address_missing, email_missing, already_registered, managed_by_novadesko, registered_elsewhere, not_registered, provider_error.

{
  "message": "Le dossier ne peut pas être inscrit sur Peppol.",
  "errors": {"peppol": ["Le dossier ne peut pas être inscrit sur Peppol."]},
  "blockers": ["L'adresse e-mail de contact est manquante."],
  "blocker_codes": ["email_missing"],
  "state": {"status": "none", "can_register": false}
}

Validierungsfehler#

{
  "message": "Le champ entry date est obligatoire. (et 1 erreur supplémentaire)",
  "errors": {
    "entry_date": ["Le champ entry date est obligatoire."],
    "lines.1.account_id": ["Le champ lines.1.account_id est obligatoire quand lines.1.account n'est pas présent."]
  }
}

Rate-Limits#

Die Limits gelten pro Minute. Sie werden bei authentifizierten Routen pro Benutzer und bei öffentlichen Routen pro IP-Adresse gezählt. Routen, die in dieser Tabelle nicht aufgeführt sind, haben kein eigenes Limit.

Jede Antwort einer begrenzten Route gibt Ihren Verbrauch an:

HTTP/1.1 200 OK
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27

Antwort 429#

HTTP/1.1 429 Too Many Requests
Retry-After: 41
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791188421
Content-Type: application/json

{"message": "Too Many Attempts."}

Warten Sie die in Retry-After angegebene Anzahl Sekunden, bevor Sie es erneut versuchen. X-RateLimit-Reset gibt den Zeitpunkt der Rücksetzung in Unix-Sekunden an.

import time
import requests

def call(method, url, **kwargs):
    for attempt in range(5):
        response = requests.request(method, url, timeout=60, **kwargs)
        if response.status_code == 429:
            # Honour the server delay, never hammer the API
            time.sleep(int(response.headers.get("Retry-After", "5")) + 1)
            continue
        if response.status_code in (500, 503):
            time.sleep(2 ** attempt)
            continue
        return response
    raise RuntimeError("NovaFisko API unavailable")

Weitere Limits#

Siehe auch#

• Idempotenz
• Paginierung
• Authentifizierung
• Konflikte und Prioritäten