ES | EN

Examples by country

⚠️ Common errors

This guide lists frequent Peru errors as returned by the Koywe / FACTO API when submission to OSE/SUNAT fails and the result object has status: 2.

Common result shape (status 2)

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - <exact text of the alert(s)> - "
}

Where the text comes from after the fixed prefix Document generated but could not be sent to the Tax bureau -:

  • Almost all messages: literal strings in module/facto/.../DocumentsMapperPeru.php (via Alertas::AgregarAlerta).
  • Only E-Fact case documented here: 1033 with description below (section 1).

1) Only E-Fact (OSE) case – current usage

1033 is a common OSE rejection when the voucher cannot be registered as submitted; the specific reason appears after description :. A typical case is that the voucher number or payload data was already registered with different information.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : 1033 - description : El comprobante fue registrado previamente con otros datos. - "
}

The text after description : is returned by the OSE; the sample above is representative.

2) Header validation (very common)

Before the OSE submission, required header fields are validated (issuer, receiver when the document type requires it, issue date, etc.). If a required field is missing, the message usually follows The field '…' is required and cannot be empty.

2.1) issue_date

issue_date is the document issue date in the header. If the key is missing, the value is empty (""), null, or not accepted as a valid date by the validator, processing stops before the OSE submission and this error appears.

Check: your create payload includes issue_date in the document header (or the field your client maps to it) using the date format required by the API (commonly YYYY-MM-DD). Also verify you are not sending the date only under another property without mapping it to issue_date.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : The field 'issue_date' is required and cannot be empty. - "
}

2.2) Issuer

Seller data uses the *`issuer_** prefix in the header (tax id, id type, legal name, address, district, department, city, country, phone, economic activity, etc.). The error names **one** field; the sample uses **issuer_tax_id_code**, but the **same pattern** applies toissuer_tax_id_type,issuer_legal_name,issuer_address,issuer_district,issuer_department,issuer_city,issuer_country_id,issuer_phone,issueractivity, and any other requiredissuer*` fields for your document type.

Check: no required value is empty or null, the RUC length is correct, and address / location fields meet Peru requirements for that voucher type.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : The field 'issuer_tax_id_code' is required and cannot be empty. - "
}

2.3) Receiver (documents that require a full receiver)

For invoices, notes, and other documents where the receiver must be fully populated, fields use the *`receiver_** prefix. If a required buyer field is missing, the error names the field (for example **receiver_tax_id_code**,receiver_legal_name`, address, etc.).

Check: receiver id type and number, legal name or full name, and fiscal address when the document type requires them.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : The field 'receiver_tax_id_code' is required and cannot be empty. - "
}

3) Sequence / series (common)

Series (document_sequence_code) and the correlative must match FACTO configuration and SUNAT rules. The cases below are the most common on document creation.

3.1) Multiple sequences without document_sequence_code

There is more than one sequence configured for the same document_type_id and the request does not specify which series to use. The backend does not pick one automatically in that situation.

Check: always send document_sequence_code (for example F001, B001) when several sequences exist for that type.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : There is more than one sequence for this document type and no document_sequence_code was provided. - "
}

3.2) No sequence in DB for a type with no default

There is no sequence in the database for that document type and the type has no auto-created default series. Without a valid sequence row, numbering cannot continue.

Check: at least one authorized series exists for that document_type_id before issuing; create or enable the series in FACTO if needed.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : There is no sequence for this document type on database - "
}

3.3) New series created (informational alert)

The submitted document_sequence_code did not exist for that document type and the system created the series (often starting the correlative at 1). The notice may appear alone or concatenated with other text in error_message. F002 in the sample is illustrative; the real message repeats the code you sent.

If that was intended (new series), usually no action is needed. If you did not want a new series, fix the code or FACTO configuration.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - The sequence code F002 did not exist for this document type. It was created with document_number 1 - "
}

4) Credit notes / references (common if you use credit notes)

Credit notes must reference the affected document with the correct document_type_id in the reference: 98 (credit note for invoice) requires reference type 96 (invoice); 155 (credit note for receipt) requires reference type 97 (receipt). Mixing types triggers these errors.

Check: the references block (references or your payload’s equivalent), identifiers of the original document, and that the reference document_type_id matches the credit note you are issuing.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : If the issued document is 98 (Credit Note for Invoice), the reference must have document_type_id = 96 (Invoice). If the issued document is 155 (Credit Note for Receipt), the reference must have document_type_id = 97 (Receipt) - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : If the issued document is 155 (Credit Note for Receipt), the reference must have document_type_id = 97 (Receipt) - "
}

5) Waybill (document_type_id = 100)

Waybills (document_type_id = 100) require valid SUNAT codes. handling_code describes the reason or type of shipment; transport_mode_code is public (01) or private (02) transport. Invalid catalog values or missing fields produce the errors below.

Check: current SUNAT catalogs for waybills and send both fields as required by the endpoint contract.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error: the values for the field handling_code must be '01', '02', '04' or '13'. - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - The field handling_code is mandatory for document_type_id = 100. - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - The values for the field transport_mode_code must be '01' (Public transport) or '02'(Private transport) - "
}

6) Taxes / decimals (common on totals)

Tax amounts (per line or aggregated) cannot have more than two decimal places. This often comes from incorrect rounding or sending IGV/ISC with too many fractional digits.

Check: normalize to two decimals before the POST; align with the Rounding guide.

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - Error : taxes cannot have more than 2 decimal places. - "
}

7) Template / PDF (POST with template)

If you request PDF generation with a template (id or code on the account) and that template does not exist or is not available to the user, generation fails. The second message means the PDF was not produced in the same response and you should fetch it with GET once processing finishes (asynchronous flow).

Check: template id/code, that the template is configured on the account, and the endpoint docs for retrieving the PDF.

(API error strings may remain in Spanish.)

"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - No se encontró la plantilla en la base de datos - "
}
"result": {
  "status": 2,
  "error_message": "Document generated but could not be sent to the Tax bureau - PDF no fue generado, favor utilizar GET para recuperar PDF - "
}

Useful links