Errors and limits

The API uses standard HTTP codes and always returns a JSON body when an error occurs.

Error format#

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

Some errors add fields of their own, for example required_ability, server_version and server_data, or blocker_codes for Peppol.

HTTP codes#

A company that exists but that you have no access to responds 404 and not 403. This is intentional: the API does not reveal the existence of a company to anyone who is not authorised to see it.

Machine codes#

Authentication and access#

Licence and caps#

Concurrency and history#

Synchronisation#

These codes appear in the result of each sync/push mutation, not as an HTTP status.

Peppol#

Peppol refusals return blocker_codes, a list among: 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}
}

Validation error#

{
  "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#

Limits apply per minute. They are counted per user for authenticated routes and per IP address for public routes. Routes that do not appear in this table have no limit of their own.

Every response from a rate-limited route shows your consumption:

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

429 response#

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

Wait the number of seconds given by Retry-After before retrying. X-RateLimit-Reset gives the reset time in Unix seconds.

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

Other limits#

See also#

• Idempotency
• Pagination
• Authentication
• Conflicts and priorities