Fouten en limieten
Hoe fouten van de EenFactuurMaken.nl REST API eruitzien, alle foutcodes per HTTP-status, rate limits, planlimieten en hoe je opnieuw probeert.
De vorm van een fout
Elke fout heeft dezelfde vorm:
json
{
"statusCode": 409,
"statusMessage": "This invoice has been issued and can no longer be changed. Create a credit note to correct it.",
"data": {
"code": "invoice_locked",
"message": "This invoice has been issued and can no longer be changed. Create a credit note to correct it.",
"details": { "status": "issued" }
}
}data.codeis een vaste code in snake_case. Gebruik die in je code; de teksten kunnen veranderen.data.detailsgeeft soms meer informatie, zoals de velden bijvalidation_failedof de controlepunten bijinvoice_not_compliant.
Validatiefouten
Bij 422 validation_failed staat in details per probleem het veld (path) en wat er mis is:
json
{
"data": {
"code": "validation_failed",
"details": [
{ "path": ["lines", 0, "unitPriceCents"], "message": "Invalid input: expected number, received string" }
]
}
}Factuur voldoet niet
Bij 422 invoice_not_compliant (bij het definitief maken) staat in details een lijst met controlepunten, elk met level (error, warning, info), field en code. Alle codes en hoe je ze oplost staan bij Factuurcontrole.
Foutcodes
| Status | Codes |
|---|---|
| 401 | unauthenticated, invalid_api_key, invalid_token |
| 402 | plan_limit_reached (maandlimiet facturen, of 25 klanten of producten op Gratis), plan_upgrade_required (functie zit in Pro) |
| 403 | bad_origin, email_recipient_not_allowed, email_sending_paused, forbidden, insufficient_scope, session_not_fresh, session_required |
| 404 | not_found, link_invalid |
| 409 | invoice_locked, invoice_not_issued, invoice_cancelled, invoice_not_cancellable, invoice_has_credit_notes, invoice_not_creditable, invoice_fully_credited, credit_note_draft_exists, invoice_already_paid, invoice_not_paid, invoice_not_remindable, reminder_too_early, reminder_in_progress, number_taken, peppol_kvk_required, layout_limit_reached, layout_read_only, recurring_inactive, recurring_run_in_progress, email_domain_exists, email_domain_taken, email_domain_provider_conflict, already_subscribed, no_active_subscription, not_cancelled, subscription_ended |
| 410 | link_expired, public_link_expired |
| 413 | logo_too_large (logo groter dan 500 KB) |
| 415 | logo_unsupported_type (alleen PNG en JPEG) |
| 422 | validation_failed, invoice_not_compliant, no_recipient, too_many_recipients, unknown_layout, recurring_template_invalid, email_domain_invalid, email_domain_public, exchange_rate_unknown_currency |
| 429 | rate_limited, email_daily_limit, email_rate_limited, invoice_resend_limit, email_platform_limit |
| 502 | email_send_failed |
| 503 | billing_unavailable, exchange_rate_unavailable |
De meest voorkomende:
| Code | Wat te doen |
|---|---|
invoice_locked | De factuur is definitief. Maak een creditnota. |
invoice_not_compliant | Los de punten met level: "error" op en probeer opnieuw. |
number_taken | Het nummer dat je meegaf bij issue bestaat al. Laat het weg voor het volgende nummer. |
plan_limit_reached | Wacht tot volgende maand, verwijder een ongebruikt concept of stap over op Pro. details.limit zegt welke limiet. |
email_recipient_not_allowed | Op Gratis mag je alleen naar het adres van de klant of je eigen adres mailen. |
peppol_kvk_required | Zonder KvK-nummer is er geen UBL. Zie PDF en e-factuur. |
Rate limits
| Limiet | Waarde |
|---|---|
| Per API-sleutel | 120 verzoeken per minuut (429 rate_limited met Retry-After) |
| Per IP-adres | 300 verzoeken per minuut |
VIES-controle (/vat-check) | 20 per minuut |
| Zie Versturen per e-mail | |
| Grootte van een verzoek | 2 MB |
Opnieuw proberen
- 429: wacht het aantal seconden uit
Retry-After(of een minuut) en probeer opnieuw. - 502 en 503: tijdelijk. Probeer het opnieuw met een oplopende wachttijd (bijvoorbeeld 2, 4 en 8 seconden).
- 4xx (behalve 429): niet opnieuw proberen zonder iets te veranderen.
- Pas op met opnieuw proberen van
POST /invoices,/senden/remind: als het eerste verzoek wél gelukt was, maak of verstuur je het dubbel. Controleer eerst met eenGETof het gelukt is.
Laatst bijgewerkt op 13 oktober 2026
Kom je er niet uit?
Mail ons op support@eenfactuurmaken.nl. Vertel wat je probeerde en wat er gebeurde, dan helpen we je verder.