Errors & Validation

Understand error responses and validation rules.

What the response means

An upload goes through two stages, and only the first one answers in the same call:

File validation (immediate). Fibek checks the file row by row. If anything fails, it responds success: false with the per-row detail and nothing is processed.
Processing (asynchronous). If the file passes validation it is queued and processed later. Whatever happens there — rows dropped because the customer or the invoice does not exist, deduplications, or a failure of the whole file — does not appear in the response.

In other words: success: true means “the file was accepted and queued”, not “all the data was loaded”. Each entity page states what gets dropped in the second stage.

Response Format

All endpoints return the same response structure.

Success Response

HTTP code 201.

{
  "success": true,
  "warnings": {
    "customers": ["File does not have .csv extension"]
  }
}

warnings is optional and does not block the upload: it flags things like an extension other than .csv, a content type other than text/csv, a file with a header and no rows, an unknown document_type, or an open CASH invoice with an outstanding balance.

Validation Error Response

This also arrives with code 201: the result is read from success.

{
  "success": false,
  "errors": {
    "customers": [
      {
        "rowIndex": 2,
        "messages": [
          "Field \"nit\" is required.",
          "Field \"email\" must have a valid email format."
        ]
      }
    ]
  }
}

rowIndex counts the file’s lines including the header, so the first data row is 2. A rowIndex of 0 means an error for the whole file rather than for a row.

HTTP Status Codes

Code	Name	Description	Action
201	Created	Request processed — the result is in the `success` field	Check `success` and, if present, `errors`
400	Bad Request	The file is missing from the form	Send the file in the correct field (for example `customersFile`)
401	Unauthorized	API Key invalid, revoked or absent	Check the API Key or create a new one
403	Forbidden	The API Key is not allowed to upload integrations	Use an API Key created in API Integration
404	Not Found	The endpoint URL does not exist	Check the path and the base URL
500	Internal Server Error	Unexpected error	Retry later

Common Validation Rules

Rule	Description
Required fields	The field must be present and cannot be empty
Column names	Exact and lowercase; spaces around the name are ignored, but no other variants are accepted
Email format	Valid email structure
Date format	`YYYY-MM-DD`; other formats are rejected. An empty cell is accepted except where stated otherwise
Numbers	Dot as the decimal separator and no thousands separator (`1000000.00`, not `1.000.000,00`)
Boolean values	Only `1` or `0`
Encoding	UTF-8

IDs without leading zeros. When the file is processed, an id made up of digits only is read as a number: 00123 becomes 123. If the same customer or invoice is written differently in two files, the rows will not match each other and are dropped with no notice. Use ids without leading zeros, or with some non-numeric character.