Errors

Status codes

Status	When
200	Success. An empty search also responds 200 with an empty pageResults (never 204).
400	Invalid query string (unparseable date, value outside an enum, unsupported parameter), or none of the fiscal IDs in a filter exist.
401	Missing Authorization header.
403	Invalid token, or the URL does not exist. See Authentication.
404	GET /customers/portal-link (customer not found), GET /customers/{id} (customer not found or not yours; 500 until CORE-2788 is deployed) and GET /accounts-payable/prepaid-expenses/{id} (fund not found or not yours).
500	Internal error.
502	GET /invoices/received when the requested page exceeds the 6 MB response limit, or when the request exceeds 29 s (organizations with many invoices). Reduce options_pageSize or retry.

The body of 400/500 responses varies by endpoint ({"errors": [...]}, {"errors": "..."} or {"error": "...", "message": "..."}); see each endpoint page.

Partial errors in GET /invoices/issued

When you filter issued invoices by customerFiscalIds, each fiscal ID is resolved to a customer first. If some of them do not exist in Buk Finance, the request still succeeds with the invoices of the ones that do, and the missing ones are reported in errors:

JSON

{
  "total": 9,
  "page": 0,
  "pageSize": 10,
  "pageResults": [],
  "errors": [
    {
      "_type": "EmptyResponseError",
      "requestName": "byFiscalId",
      "requestParams": { "fiscalId": "121212121" }
    }
  ]
}

Each element of errors is an object, not a string. The problematic fiscal ID comes normalized (no dots or dash) in requestParams.fiscalId. If none of the fiscal IDs exist, the response is 400 with the same errors array.

GET /invoices/received always returns errors: []; if none of the issuerFiscalIds exist it responds 400.

Handling partial errors:

JavaScript

const data = await response.json();

for (const error of data.errors) {
  if (error._type === "EmptyResponseError") {
    console.warn("Fiscal ID not found:", error.requestParams?.fiscalId);
  } else {
    console.warn("Non-fatal error:", error);
  }
}

console.log("Invoices:", data.pageResults.length, "of", data.total);

Python

data = response.json()

for error in data["errors"]:
    if error.get("_type") == "EmptyResponseError":
        print("Fiscal ID not found:", error.get("requestParams", {}).get("fiscalId"))
    else:
        print("Non-fatal error:", error)

print("Invoices:", len(data["pageResults"]), "of", data["total"])