API error handling: HTTP status codes and error messages

When problems occur, the faktoora API returns standardized HTTP status codes and meaningful error messages. This article helps you understand and fix common errors.

HTTP 404: Invoice not found

If you try to retrieve or change an invoice via the API and receive a 404 error message, the requested resource was not found.

Common causes:

• Wrong faktooraId: Check that you are using the correct faktooraId. It was returned in the response under faktooraId when the invoice was created.
• Asynchronous invoice creation: If you try to retrieve an invoice with GET immediately after creating it, a 404 may occur. The API responds to POST requests with 202 Accepted and a faktooraId. The invoice is processed asynchronously and may not be retrievable for a short time. Use the returned faktooraId to retrieve the status, or use webhooks to be notified when processing is complete.
• Invoice was deleted: The requested invoice no longer exists in the system.

Solution:

Validate the faktooraId in your request. For newly created invoices: wait a few seconds or check the processing status with GET /invoices/{faktooraId}/status before accessing the complete invoice record.

HTTP 400: Bad request

An HTTP 400 error indicates a validation problem in the request. This is the most common error in API integrations.

Incorrect or missing required parameters

Causes:

• Required fields are missing (e.g. invoiceNumber, issueDate, buyer, seller)
• Field formats are wrong (e.g. a date not in the format YYYYMMDD)
• Unknown or invalid values for enumerated fields (e.g. invoiceTypeCode)

Solution:

Check the API documentation or the OpenAPI schema for required fields and their valid value ranges. The error response contains hints about the faulty field.

Validation error for decimal numbers: "must be multiple of 0.01"

When you submit amounts in the allowance array (discounts or surcharges) or other monetary fields, all decimal numbers must be limited to a maximum of 2 decimal places.

The error occurs with:

• allowance[].amount with more than 2 decimal places (e.g. 10.005 instead of 10.00)
• Similar problems with other monetary fields

Solution:

Round all monetary amounts to 2 decimal places. Example:

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

HTTP 400: "Docx template is disabled"

This error message means that you tried to use a DOCX or Typst template when creating an invoice, but the templating feature is not enabled.

Causes:

• Templating features are not enabled for your account
• You pass the template field in the request even though the feature is not activated

Solution:

There are two options:

1. Omit the template field: Remove the template object from the request to use the default invoice template.
2. Enable the feature: Contact faktoora support to have the templating features (DOCX or Typst templating) activated for your account.

Once the features are enabled, you can specify the name of your custom template with the template.label parameter.

Allowance is not shown in the PDF

If you pass allowance data via the API but it does not appear in the generated invoice PDF or is not deducted from the total, there can be several causes.

Common causes:

• Missing tax rates: Every allowance entry requires a taxes array with at least one VAT entry. Without a correct tax configuration, the allowance may be ignored.
• The invoice format does not support allowances: Not all invoice formats (e.g. simple PDF invoices in the simple format) support allowances. Allowances are processed correctly in the structured formats (ZUGFeRD, XRechnung).

Solution:

Make sure that:

1. Every allowance entry contains a taxes array with at least one entry:

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

2. You use a structured invoice format that supports allowances (format: "zf:2" or format: "xrechnung").

HTTP 500: Internal server error

A 500 error means that an unexpected error occurred on the server. The error Cannot read properties of undefined indicates a null-pointer-like error in the code.

Common causes:

• Invalid or inconsistent data structures: Fields are present, but their contents do not meet expectations.
• Missing required links: If you reference an object (e.g. a customer via buyer.faktooraCustomerId), the reference may not be resolved.
• Temporary error: Occasional 500 errors can also indicate technical server downtime.

Solution:

1. Check your request for completeness and validity, especially references to external resources (customer IDs, template IDs).
2. Retry the request after a short time.
3. If the error persists, contact faktoora support with details on:
   • The exact API request (without keys or sensitive data)
   • The timestamp of the error
   • The response or error message you received

Best practices for an error-free API integration

• Validate locally: Check your data before sending it to the API: formats, required fields, length restrictions.
• Use the demo environment: Test against https://api.demo.faktoora.com/api/v1 first instead of the production environment https://api.faktoora.com/api/v1.
• Handle asynchronous processing: Invoice creation is asynchronous. Do not retrieve the status immediately afterwards; use webhooks or polling with an interval instead.
• Log responses: Store the complete API response, especially for 400 and 500 errors; it contains the hint about the faulty field.
• Check the documentation: The OpenAPI documentation contains all requirements for each endpoint.