Fouten en limieten

De API gebruikt de standaard-HTTP-codes en geeft bij een fout altijd een JSON-body terug.

Formaat van een fout#

{
  "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."]
  }
}

Sommige fouten voegen eigen velden toe, bijvoorbeeld required_ability, server_version en server_data, of blocker_codes voor Peppol.

HTTP-codes#

Een dossier dat bestaat maar waartoe u geen toegang hebt, antwoordt 404 en niet 403. Dat is bewust zo: de API geeft het bestaan van een dossier niet prijs aan wie er niet toe gemachtigd is.

Machinecodes#

Authenticatie en toegang#

Licentie en plafonds#

Gelijktijdigheid en geschiedenis#

Synchronisatie#

Deze codes verschijnen in het resultaat van elke mutatie van sync/push, niet als HTTP-status.

Peppol#

De Peppol-weigeringen geven blocker_codes terug, een lijst uit: 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}
}

Validatiefout#

{
  "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."]
  }
}

Snelheidslimieten#

De limieten gelden per minuut. Ze worden geteld per gebruiker voor de geauthenticeerde routes en per IP-adres voor de publieke routes. De routes die niet in deze tabel staan, hebben geen eigen limiet.

Elk antwoord van een gelimiteerde route vermeldt uw verbruik:

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

Antwoord 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."}

Wacht het aantal seconden dat Retry-After aangeeft voordat u het opnieuw probeert. X-RateLimit-Reset geeft het tijdstip van de reset in Unix-seconden.

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")

Andere limieten#

Zie ook#

• Idempotentie
• Paginering
• Authenticatie
• Conflicten en prioriteiten