Overview
This page is the reference for error handling. It shows the error body formats, the status codes of each endpoint, the frequent validation rules and the correct retry behaviour.Error body formats
The API uses three formats. Read the HTTP status code first, then parse the body.Error with a text message
Most errors return a JSON object with one field,detail, that contains a string.
Request validation error (422)
When a request does not match the schema of the endpoint (a missing field, a wrong type, a wrong date format),detail is an array. Each item identifies one field.
HTTPValidationError) defines only loc, msg and type. An item can contain more keys, for example input (the value that you sent) and ctx. Do not make your code depend on these extra keys.
422 with a text message in detail, for example "Invalid file type". Your code must accept a string and an array in detail.The OpenAPI spec declares a text detail (ErrorResponse) for the 422 of these endpoints: create a document (from JSON, UBL or PDF), validate JSON, validate UBL, validate a stored document, the attachment endpoints except delete, get the UBL, reprocess an inbound email, the Peppol ID check, the two lookup endpoints, create and update a webhook, and test a webhook. A request that does not match the schema can also give the array format on these endpoints.Validation result
The validation endpoints (POST /api/validate/json, POST /api/validate/ubl and POST /api/documents/{document_id}/validate) return a success status when the document breaks a rule: 201 Created for the two /api/validate/ endpoints and 200 OK for the validation of a stored document. The result is in the body: is_valid is false and issues contains the rule failures.
POST /api/validate/json also returns the generated UBL in ubl_document, also when is_valid is false. This example does not show it. Use the UBL to find the element of each issue, but do not send a UBL that is not valid.
BR-CO-15 or PEPPOL-EN16931-R120. A failure of the XML schema has the value xsd-validation.fatal makes the document invalid. An issue with the rule_id xsd-validation also makes the document invalid. A result with is_valid true can contain issues with other values, for example warnings.POST /api/documents/{document_id}/validate uses a stricter rule: each issue whose flag is not warning makes the document invalid. POST /api/validate/ubl can return an issue with no flag, with is_valid true. Thus also make sure that each issue has a flag. Do not use type for this check: an issue with "flag": "warning" can also have "type": "error". See Look for errors in the issues.XSD, CEN-EN16931-UBL, PEPPOL-EN16931-UBL or PEPPOL-EN16931-UBL-SB.HTTP status codes
406 when you create a document and 400 when you send it. A Peppol ID that is not owned by your company gives 406 when you create a document and 409 when you send it.Create document errors (406)
POST /api/documents/ returns 406 Not Acceptable for four causes. No document is created.
The Peppol sender or receiver cannot be derived
The Peppol sender or receiver cannot be derived
vendor_tax_id and customer_tax_id (or the company IDs) are present and correct.The sender is not a Peppol ID of your company
The sender is not a Peppol ID of your company
9925:be1018265814 agrees with the stored Peppol ID 9925:BE1018265814. Use the vendor identifiers of your company. Use GET /api/me/ to see the Peppol IDs of your company.For a self-billing document, the customer is the sender on Peppol. Thus the API examines the Peppol ID of the customer, and the message also starts with Derived sender. See Ownership rule.The totals in the JSON are not correct
The totals in the JSON are not correct
Total tax mismatch, Total discount mismatch, Invoice total mismatch or Amount due. See Invoice totals and calculations.The same Document is not valid detail also occurs when vatex is VATEX-EU-O and a tax ID is present. With this code, vendor_tax_id and customer_tax_id must be empty:customer tax ID. If the two IDs are present, the list contains the two texts.The generated UBL is not valid for Peppol BIS Billing 3.0
The generated UBL is not valid for Peppol BIS Billing 3.0
detail contains the messages of the rules that failed, without the rule identifiers. Send the same payload to POST /api/validate/json to get the full list of issues with rule_id. Then see Frequent validation rules.POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.Send errors
POST /api/documents/{document_id}/send does these checks in sequence.
406 for the send call, but the send call does not return 406. If the sender Peppol ID is not a Peppol ID of your company, the send call returns 409. To find the rule failures of a stored document, use POST /api/documents/{document_id}/validate.
Peppol ID routing
When you send a document, the API finds each of the four Peppol values (sender scheme and identifier, receiver scheme and identifier) in this order:- The query parameter of the send request.
- The Peppol ID that the API stored with the UBL of the document when you created it. For a document that you created from UBL, this is the
cbc:EndpointIDof the party. - The derivation from the identifiers in the document:
customer_peppol_idfirst for the customer, thenvendor_company_id/customer_company_idandvendor_tax_id/customer_tax_id. The API usescustomer_peppol_idonly in the formscheme:identifier, for example0208:0848934496. ForSELFBILLING_INVOICEandSELFBILLING_CREDIT_NOTE, the direction is reversed: the API derives the sender from thecustomer_*fields and the receiver from thevendor_*fields.
0208 and the enterprise number: the tax ID BE1018265814 gives the Peppol ID 0208:1018265814. If a tax ID has no country prefix, the API uses the country code at the end of the address (for example 1980 Zemst, BE). Always give the VAT number with its country prefix, because rule BR-CO-09 rejects a VAT number without it. For the scheme that the API derives in other countries, see Peppol ID schemes.
When the API sends the document on the Peppol network, it writes the final sender and receiver values in the cbc:EndpointID elements of the UBL that it transmits. The other content of the UBL does not change.
The derived scheme can be different from the scheme that the receiver registered. Thus the best practice is to give all four query parameters:
email. This parameter is deprecated. Do not use it.
The API returns 400 if it cannot find a complete sender and receiver Peppol ID. It returns 409 if the sender Peppol ID is not one of the peppol_ids of your company.
Frequent validation rules
A document is in state FAILED
After an accepted send call, the document is in state TRANSIT. The transmission occurs in the background. If all transmission attempts fail, the state becomes FAILED and the document.sent.failed webhook event is sent. See Retry behaviour for the number of attempts.
Read the timeline
GET /api/documents/{document_id}/timeline returns the events of the document. A send request that fails during the transmission gives one event with event_type send_failed. A send request that fails before the transmission, for example with 409, gives no event. The automatic attempts in one send request give no separate events. The details object shows the sender and receiver Peppol IDs that the API used.Examine the receiver
details is correct. Then call GET /api/validate/peppol-id?peppol_id=0208:0848934496 to see if the receiver is registered on the Peppol network. See Look up Peppol participants.Send again
POST /api/documents/{document_id}/send again. The API accepts a send call for a document in state FAILED. If the Peppol IDs were wrong, give the correct IDs as query parameters. See Send a failed document again.Retries and idempotency
Which errors to retry
Rate limits
The rate limit applies to each API key and only to these endpoints:POST /api/documents/POST /api/documents/ublPOST /api/validate/jsonPOST /api/validate/ubl
429 with a Retry-After header.
The value of Retry-After is fixed. It is the length of the time window in seconds, not the time until your counter starts again. If the request after the wait also gets 429, wait longer before the next attempt.
429.
No idempotency key
The API has no idempotency key. If you repeatPOST /api/documents/, the API creates a second draft with the same invoice_id. A send call is different: a second send call for a document in state TRANSIT or SENT returns 405 and does not transmit the document again.
If a create call ends without a response (a timeout or a network error), find out if the document exists before you create it again. Search the drafts for your invoice number. This list contains documents in the states DRAFT, TRANSIT and FAILED. For documents that are sent, use GET /api/outbox/ with the same search parameter. Find duplicates before a retry gives the full procedure.
search parameter finds a part of the invoice number, the vendor name, the customer name or the note, thus compare invoice_id for an exact match.
Troubleshooting
422 with "Field required" and loc ["body", "file"]
422 with "Field required" and loc ["body", "file"]
multipart/form-data upload with a part that has the name file. You sent the XML or the PDF as the raw request body. With cURL, use -F "file=@invoice.xml" and do not set the Content-Type header manually. See Send UBL documents and Create documents from PDF.422 with "Invalid file type" from the UBL validation
422 with "Invalid file type" from the UBL validation
POST /api/validate/ubl accepts only a file part with the content type application/xml or text/xml. Some HTTP clients send a file part as application/octet-stream. Set the content type of the part. With cURL, use -F "file=@invoice.xml;type=application/xml". With Python requests, use files={"file": ("invoice.xml", open("invoice.xml", "rb"), "application/xml")}.401 on each request
401 on each request
Authentication required means that the request has no Authorization: Bearer header. Invalid authentication means that the API key is not known or is deleted. Make sure that the header has the format Authorization: Bearer <key> and that the key is the key of the company that you want to use. See Authentication.429 during a bulk import
429 during a bulk import
Retry-After header, wait, then continue. Send the requests in sequence, not in parallel.The customer did not receive the document
The customer did not receive the document
GET /api/documents/{document_id}.DRAFT: the document was not sent. Call the send endpoint.TRANSIT: the transmission is in progress.FAILED: see A document is in stateFAILED.SENT: the access point of the receiver accepted the document. Ask the customer to look in the software that is connected to their Peppol ID. Read the timeline to see which receiver Peppol ID was used.
The test email did not arrive
The test email did not arrive
company_email field of GET /api/me/. Make sure that it is set, and look in the spam folder. If company_email is empty, the send call returns 400 with Tenant is in test mode but no company email is set. See Send errors and Test mode and sandbox companies.The webhook signature does not match
The webhook signature does not match
data field only. Make sure that you use the secret of the correct webhook and that you serialise the payload as the Webhooks guide shows.The sandbox inbox is empty
The sandbox inbox is empty