Erreurs et limites

L'API utilise les codes HTTP standards et renvoie toujours un corps JSON en cas d'erreur.

Format d'une erreur#

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

Certaines erreurs ajoutent des champs propres, par exemple required_ability, server_version et server_data, ou blocker_codes pour Peppol.

Codes HTTP#

Un dossier qui existe mais auquel vous n'avez pas accès répond 404 et non 403. C'est voulu : l'API ne révèle pas l'existence d'un dossier à qui n'y est pas autorisé.

Codes machine#

Authentification et accès#

Licence et plafonds#

Concurrence et historique#

Synchronisation#

Ces codes apparaissent dans le résultat de chaque mutation de sync/push, pas comme statut HTTP.

Peppol#

Les refus Peppol renvoient blocker_codes, une liste parmi : 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}
}

Erreur de validation#

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

Limites de débit#

Les limites s'appliquent par minute. Elles sont comptées par utilisateur pour les routes authentifiées et par adresse IP pour les routes publiques. Les routes qui ne figurent pas dans ce tableau n'ont pas de limite propre.

Chaque réponse d'une route limitée indique votre consommation :

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

Réponse 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."}

Attendez le nombre de secondes indiqué par Retry-After avant de réessayer. X-RateLimit-Reset donne l'instant de remise à zéro en secondes Unix.

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

Autres limites#

Voir aussi#

• Idempotence
• Pagination
• Authentification
• Conflits et priorités