Foutafhandeling | API-documentatie

Hoe fouten eruitzien

Gaat er iets mis, dan krijg je een passende statuscode en een JSON-antwoord in deze vorm (rechts een voorbeeld: een aanvraag die een fout geeft, met het antwoord):

Reageer in je code op code, niet op message. De tekst van message kan verduidelijkt worden zonder dat de betekenis van de code verandert.

Foutcodes

Status	Code	Betekenis
400	`invalid_parameter`	Een parameter heeft een ongeldige waarde of komt dubbel voor, bijvoorbeeld een `limit` buiten 1 tot en met 1000, of `modified_since` zonder geldig tijdstip.
400	`unknown_parameter`	Een parameter die op deze tabel niet bestaat. Bij eigen tabellen: alles behalve `limit`, `cursor` en `modified_since`.
400	`invalid_filter`	Een filter klopt niet: onbekende kolom, operator die niet bij het kolomtype past, ongeldige waarde, meer dan 10 filters of dubbele filters.
400	`invalid_cursor`	De cursor is ongeldig, ouder dan 24 uur, of hoort bij andere parameters of een andere tabel. Begin opnieuw zonder cursor.
400	`incremental_not_supported`	`modified_since` is gebruikt op een tabel die dit niet ondersteunt.
401	`invalid_key`	De sleutel ontbreekt, is onbekend, is ingetrokken of is verlopen.
403	`subscription_inactive`	Je proefperiode is verlopen of je abonnement is niet actief.
404	`unknown_table`	De koppeling of tabel bestaat niet.
404	`unknown_connection`	De administratie in `connection` bestaat niet of hoort niet bij deze koppeling in jouw organisatie.
409	`table_recomputed`	Alleen bij eigen tabellen: de tabel is opnieuw berekend tijdens het ophalen. Begin opnieuw zonder cursor.
429	`rate_limited`	Je hebt een limiet bereikt, zie Gebruikslimieten. Wacht het aantal seconden uit `Retry-After`.
500	`internal_error`	Er ging iets mis aan onze kant. Probeer het later opnieuw.
503	`service_unavailable`	De API is tijdelijk niet bereikbaar. Probeer het opnieuw na het aantal seconden uit `Retry-After`.

Wat je met welke fout doet

400, 404 en 409: de aanvraag moet anders. Opnieuw proberen met dezelfde aanvraag heeft geen zin, behalve bij 409: begin dan opnieuw zonder cursor.
401 en 403: controleer je sleutel en je abonnement, zie Authenticatie.
429, 500 en 503: probeer het opnieuw. Wacht bij 429 en 503 de tijd uit Retry-After en verdubbel bij 500 je wachttijd bij elke nieuwe poging.

Onze tip: log de foutcode samen met je eigen aanvraaggegevens (pad en parameters, nooit de sleutel). Dat maakt troubleshooten achteraf een stuk sneller.

GET https://app.apiboard.nl/api/v1/e-boekhouden/facturen?status=betaald HTTP/1.1 Host: app.apiboard.nl Authorization: Bearer apib_live_JOUW_SLEUTEL # De tabel heeft geen kolom status, dus dit geeft een 400 met code invalid_filter.

curl -H "Authorization: Bearer apib_live_JOUW_SLEUTEL" \ "https://app.apiboard.nl/api/v1/e-boekhouden/facturen?status=betaald" # De tabel heeft geen kolom status, dus dit geeft een 400 met code invalid_filter.

import time import requests TOKEN = "apib_live_JOUW_SLEUTEL" URL = "https://app.apiboard.nl/api/v1/e-boekhouden/facturen" def haal_op(params, pogingen=5): wacht = 1 for _ in range(pogingen): resp = requests.get(URL, params=params, headers={"Authorization": f"Bearer {TOKEN}"}) if resp.ok: return resp.json() code = resp.json()["error"]["code"] # reageer op code, niet op message if resp.status_code in (429, 503): time.sleep(int(resp.headers.get("Retry-After", wacht))) elif resp.status_code == 500: time.sleep(wacht) wacht *= 2 # verdubbel de wachttijd bij elke poging else: # 400, 401, 403, 404, 409: dezelfde aanvraag opnieuw proberen heeft geen zin raise RuntimeError(f"{resp.status_code} {code}") raise RuntimeError("Te veel pogingen") body = haal_op({"status": "betaald"}) print(f"{len(body['data'])} rijen.")