Foutafhandeling in de API: HTTP-statuscodes en foutmeldingen

De faktoora-API geeft bij problemen gestandaardiseerde HTTP-statuscodes en duidelijke foutmeldingen terug. Dit artikel helpt u veelvoorkomende fouten te begrijpen en op te lossen.

HTTP 404: factuur niet gevonden

Als u via de API een factuur probeert op te vragen of te wijzigen en een 404-foutmelding krijgt, betekent dit dat de gevraagde resource niet is gevonden.

Veelvoorkomende oorzaken:

• Onjuiste faktooraId: controleer of u de juiste faktooraId gebruikt. Deze is bij het aanmaken van de factuur in de response onder faktooraId teruggegeven.
• Asynchrone aanmaak van facturen: als u een factuur direct na het aanmaken met GET wilt opvragen, kan een 404 optreden. De API antwoordt op POST-requests met 202 Accepted en een faktooraId. De factuur wordt asynchroon verwerkt en kan korte tijd niet op te vragen zijn. Gebruik de teruggegeven faktooraId om de status op te vragen of gebruik webhooks om een melding te krijgen wanneer de verwerking is afgerond.
• Factuur is verwijderd: de gevraagde factuur bestaat niet meer in het systeem.

Oplossing:

Valideer de faktooraId in uw request. Voor nieuw aangemaakte facturen: wacht enkele seconden of controleer de verwerkingsstatus met GET /invoices/{faktooraId}/status voordat u het volledige factuurrecord opvraagt.

HTTP 400: ongeldig verzoek

Een HTTP 400-fout wijst op een validatieprobleem in het verzonden request. Dit is de meest voorkomende fout bij API-integraties.

Onjuiste of ontbrekende verplichte parameters

Oorzaken:

• Verplichte velden ontbreken (bijv. invoiceNumber, issueDate, buyer, seller)
• Veldformaten zijn onjuist (bijv. datum niet in het formaat YYYYMMDD)
• Onbekende of ongeldige waarden voor velden met een vaste waardelijst (bijv. invoiceTypeCode)

Oplossing:

Raadpleeg de API-documentatie of het OpenAPI-schema voor de verplichte velden en hun geldige waarden. De foutresponse bevat aanwijzingen over het onjuiste veld.

Validatiefout bij decimale getallen: "must be multiple of 0.01"

Als u bedragen in de allowance-array (kortingen of toeslagen) of in andere geldvelden verstuurt, mogen alle decimale getallen maximaal 2 decimalen hebben.

De fout treedt op bij:

• allowance[].amount met meer dan 2 decimalen (bijv. 10.005 in plaats van 10.00)
• Vergelijkbare problemen met andere geldvelden

Oplossing:

Rond alle geldbedragen af op 2 decimalen. Voorbeeld:

{
  "allowance": [
    {
      "indicator": "discount",
      "reason": "Mengenrabatt",
      "amount": 10.50,
      "taxes": [
        {
          "typeCode": "VAT",
          "categoryCode": "S",
          "rate": 19
        }
      ]
    }
  ]
}

HTTP 400: "Docx template is disabled"

Deze foutmelding betekent dat u bij het aanmaken van een factuur een DOCX- of Typst-sjabloon hebt willen gebruiken, maar dat de sjabloonfunctie niet is geactiveerd.

Oorzaken:

• De sjabloonfuncties zijn voor uw account niet geactiveerd
• U geeft het veld template mee in het request, hoewel de functie niet is vrijgegeven

Oplossing:

Er zijn twee mogelijkheden:

1. Sjabloonveld weglaten: verwijder het template-object uit het request om het standaard factuursjabloon te gebruiken.
2. Functie activeren: neem contact op met de support van faktoora om de sjabloonfuncties (DOCX- of Typst-sjablonen) voor uw account te laten vrijgeven.

Als de functies geactiveerd zijn, kunt u met de parameter template.label de naam van uw eigen sjabloon opgeven.

Allowance wordt niet in de pdf weergegeven

Als u allowance-gegevens via de API meegeeft, maar deze niet in de gegenereerde factuur-pdf verschijnen of niet van het totaalbedrag worden afgetrokken, kan dat meerdere oorzaken hebben.

Veelvoorkomende oorzaken:

• Ontbrekende belastingtarieven: elke allowance-regel vereist een taxes-array met minstens één VAT-regel. Zonder correcte belastingconfiguratie wordt de allowance mogelijk genegeerd.
• Factuurformaat ondersteunt geen allowances: niet alle factuurformaten (bijv. eenvoudige pdf-facturen in het formaat simple) ondersteunen allowances. In de gestructureerde formaten (ZUGFeRD, XRechnung) worden allowances correct verwerkt.

Oplossing:

Zorg ervoor dat:

1. Elke allowance-regel een taxes-array met minstens één regel bevat:

"taxes": [
  {
    "typeCode": "VAT",
    "categoryCode": "S",
    "rate": 19
  }
]

2. U een gestructureerd factuurformaat gebruikt dat allowances ondersteunt (format: "zf:2" of format: "xrechnung").

HTTP 500: interne serverfout

Een 500-fout betekent dat er op de server een onverwachte fout is opgetreden. De fout Cannot read properties of undefined wijst op een fout in de code die lijkt op een null-pointerfout.

Veelvoorkomende oorzaken:

• Ongeldige of inconsistente datastructuren: velden zijn aanwezig, maar hun inhoud voldoet niet aan de verwachtingen.
• Ontbrekende vereiste koppelingen: als u naar een object verwijst (bijv. een klant via buyer.faktooraCustomerId), wordt de verwijzing mogelijk niet opgelost.
• Tijdelijke fout: incidentele 500-fouten kunnen ook wijzen op technische uitval van de server.

Oplossing:

1. Controleer uw request op volledigheid en geldigheid, in het bijzonder verwijzingen naar externe resources (klant-ID's, sjabloon-ID's).
2. Probeer het request na korte tijd opnieuw.
3. Blijft de fout optreden, neem dan contact op met de support van faktoora en vermeld:
   • het exacte API-verzoek (zonder sleutel of gevoelige gegevens)
   • het tijdstip van de fout
   • de response of foutmelding die u hebt ontvangen

Best practices voor een foutloze API-integratie

• Valideer lokaal: controleer uw gegevens voordat u ze naar de API stuurt: formaten, verplichte velden, lengtebeperkingen.
• Gebruik de demo-omgeving: test eerst tegen https://api.demo.faktoora.com/api/v1 in plaats van tegen de productieomgeving https://api.faktoora.com/api/v1.
• Houd rekening met asynchrone verwerking: het aanmaken van facturen verloopt asynchroon. Vraag de status niet direct daarna op, maar gebruik webhooks of polling met een tussenpoos.
• Log responses: sla de volledige API-response op, vooral bij 400- en 500-fouten; deze bevat de aanwijzing over het onjuiste veld.
• Raadpleeg de documentatie: de OpenAPI-documentatie bevat alle vereisten voor elk endpoint.