Error handling & error codes
When a Számla Agent request fails (e.g. invoice or receipt is not created), the cause is usually in the request data or parameters. Sending the same request again without changing anything will not resolve the problem.
Do not retry in a loop
Do not program your system to retry failed requests automatically until success. Real cases have led to tens of thousands of duplicate requests overnight and overloaded servers. If a request fails, fix the request (or wait for human/operator action), then try again with a corrected call.
Test environment: maximum 500 invoices per 10 minutes
During the testing phase, do not generate more than 500 invoices within 10 minutes in the testing environment. For details on creating and using the test account (the user can turn it on and off), see the knowledge base.
Retry limit
Maximum 5 attempts per request
You may send the same request to Számla Agent at most five times. If all five attempts are unsuccessful, you must stop and contact the operator of your webshop (or the responsible person). Do not continue with that invoice/receipt until the issue is resolved by human intervention.
Számla Agent is not responsible if an invoice or receipt could not be generated. Repeated violations of these rules (e.g. excessive retries or unnecessary server load) may result in banning the calling party from the service.
Plain-text error format
When <valaszVerzio> is 1 (or not set), errors arrive as a plain-text message in the response body, not as XML. The structure looks like this:
[ERR] Error message here. ---------- t.getMessage(): Error message here.
---------- [CEG:NNN] [MODUL:...] [INSTANCE:...] Error details [LOCATION:...]
ClassName.method(File.java:line)
...
java.lang.Thread.run(Thread.java:662)
The important part is the text between [ERR] and ------------. Everything after that can be ignored.
Operations that can return this format: generating invoice, reversing invoice, registering a credit entry, querying document (PDF).
Error codes and messages
Look up the code returned in the response below and adjust your request or process accordingly. The first column is the error code, the second is the message received in the response (in Hungarian), and the last column has the English translation and explanation.
| CODE | DESCRIPTION | TRANSLATION |
|---|---|---|
1 | Rendszerkarbantartás, kérem próbálja meg pár perc múlva. | System Maintenance, please try again in a few minutes. Internal error in Számla Agent. No action is required from the webshop, the maintenance team of Számlázz.hu is notified and will take action. |
3 | Sikertelen bejelentkezés | Login error. Invalid login name or password. |
53 | Hiányzó XML fájl. | Missing XML file. The XML was probably not sent as a file, but as an input content of an HTML. |
54 | E-számla készítés nincs engedélyezve. | The issuing of e-invoices is not permitted. Your subscription package probably does not contain it, or there is no own certificate uploaded. In this case, you need to accept that KBOSS.hu Kft. can use its own certificate for the invoices. |
55 | E-számla aláírása sikertelen. | E-invoice signature was unsuccessful. Either your certificate expired or the timestamp server could not be reached. |
57 | XML beolvasási hiba. | XML reading error. There is an error in the sent XML file. The response body contains more information. XML that fails XSD validation can also receive this code, see Sending requests / XML validation and misspelled tags. |
71 | Már létező rendelésszám. Az ismétlődés engedélyezhető a Beállítások oldalon. | The order number already exists. The "Disable order number repetition" setting is enabled in the account and a document of the same type already uses this order number. See the Generating invoice / Order number and duplicate checking page. |
135 | Számla Agent futtatásához kérjük böngészőkében lépjen ki a Számlázz.hu rendszerből | In order to run Számla Agent, please log out from Számlázz.hu in your browser. This can happen in case you are logged in to Számlázz.hu in one browser window and in another you are testing the XML with the test HTML file or a curl POST request. |
136 | Bejelentkezési hiba ... Kérjük lépjen be a Számlázz.hu rendszérbe böngészőn keresztül. | Login error ... Please log in to the Számlázz.hu system via a browser. Possible reasons: the subscription has expired; there is a pending invoice towards Számlázz.hu; there is a delay in payment. In these cases please log in to Számlázz.hu and check your subscription under Szolgáltatáscsomagom. |
152 | Már létező rendelésszám: XXX. Az ismétlődés engedélyezhető a Beállítások oldalon. | Same as error 71, but the message also contains the duplicated order number. See the Generating invoice / Order number and duplicate checking page. |
164 | Ezt a funkciót csak olyan felhasználó veheti igénybe, aki egyetlen Számlázz.hu-s fiókhoz férhet hozzá. Több fiókhoz történő hozzáférés kizárja a funkció használatát. | The user is allowed to access only one company's billing account. If the user has access to more than one billing account, the operation will fail. Consider using an Agent key for authentication. |
202 | A megadott számlaszám előtag nem megfelelő. Agent használat során, csak a Számlázz.hu rendszerében korábban regisztrált előtagokat lehet használni. | The provided invoice prefix cannot be used. The <szamlaszamElotag> field is either empty or contains a prefix that is not registered in the billing account. The available prefixes can be found in the Settings / Prefixes (Beállítások / Előtagok) menu in Számlázz.hu. |
259 | A tétel nettó értéke nem megfelelő; nettó érték = nettó egységár x mennyiség. Termék: ** | The NET value of the item is not correct; <nettoErtek> = <nettoEgysegar> * <mennyiseg>. The response body contains the name of the wrong product after the "Termék" word. |
260 | A tétel áfa értéke nem megfelelő; áfa érték = tétel nettó értéke x áfakulcs mértéke / 100. Termék: ** | The VAT value of the item is not correct; <afaErtek> = <nettoErtek> * <afakulcs> / 100. The response body contains the name of the wrong product after the "Termék" word. |
261 | A tétel bruttó értéke nem megfelelő; bruttó érték = tétel nettó értéke + tétel áfa értéke. Termék: ** | The gross value of the item is not correct; <bruttoErtek> = <nettoErtek> + <afaErtek>. The response body contains the name of the wrong product after the "Termék" word. On HUF receipts this check requires an exact match, see Item amounts and rounding. |
262 | A tétel nettó értéke nem megfelelő; nettó érték = nettó egységár x mennyiség. Termék: ** | The NET value of the item is not correct; <nettoErtek> = <nettoEgysegar> * <mennyiseg>. The response body contains the row number of the wrong product after the "Termék" word. |
263 | A tétel áfa értéke nem megfelelő; áfa érték = tétel nettó értéke x áfakulcs mértéke / 100. Termék: ** | The VAT value of the item is not correct; <afaErtek> = <nettoErtek> * <afakulcs> / 100. The response body contains the row number of the wrong product after the "Termék" word. |
264 | A tétel bruttó értéke nem megfelelő; bruttó érték = tétel nettó értéke + tétel áfa értéke. Termék: ** | The gross value of the item is not correct; <bruttoErtek> = <nettoErtek> + <afaErtek>. The response body contains the row number of the wrong product after the "Termék" word. |
363 | A tétel bruttó értékének egész számnak kell lennie. Termék: ** | Receipt only: the gross value (<brutto>) of the item must be a whole number on HUF receipts. See Item amounts and rounding. |
364 | A tétel nettó értéke maximum 2 tizedes jegyet tartalmazhat. Termék: ** | Receipt only: the net value (<netto>) of the item may contain at most 2 decimal places on HUF receipts. See Item amounts and rounding. |
365 | A tétel áfa értéke maximum 2 tizedes jegyet tartalmazhat. Termék: ** | Receipt only: the VAT value (<afa>) of the item may contain at most 2 decimal places on HUF receipts. See Item amounts and rounding. |
537 | Agent-en maximálisan 400 törlőkód adható egy tételhez. | The number of data erasure codes that can be requested for an item has been reached. The error message always informs you of the maximum number of data eraser codes. |
538 | Adattörlő kód demo-ban és tesztfiókban nem használható. | Data deletion code cannot be used in demo and test accounts. |
539 | Nincs bekapcsolva az adattörlőkód használata a beállítások menüben | Use of the data deletion code is not enabled in the settings menu. You must enable the Data Eraser code in the Billing settings menu. |
551 | Egyszerűsített számlakép bekapcsolt OSS és nem magyar adószám esetén nem használható. | The simplified invoice image cannot be used when OSS (One Stop Shop) taxation is enabled in the account or the seller's tax number is not Hungarian. Every Agent request with simpleItems=true fails with this error in these cases. See Simplified item data for tour operators. |
552 | Egyszerűsített számlakép esetén maximum két tétel adható meg | With the simplified invoice image (simpleItems=true) at most two items are allowed on the document; the final invoice is an exception, where up to four items are allowed because of the negative items (2 negative + 2 new). This check runs before the VAT rate check. See Simplified item data for tour operators. |
553 | Egyszerűsített számlakép esetén érvénytelen adókulcs. | Invalid VAT rate with the simplified invoice image. Only Hungarian VAT rates are allowed: 0, 5, 18, 27, TAM, AAM, K.AFA, F.AFA. A single item with an invalid VAT code rejects the whole document. See Simplified item data for tour operators. |
554 | Egyszerűsített számlaképet használó számlát nem lehet helyesbíteni. | An invoice issued with the simplified invoice image cannot be corrected, even if the corrective request does not contain the simpleItems field. The only negative-direction document for such an invoice is the reversal (storno). See Simplified item data for tour operators. |
555 | Egyszerűsített számlakép esetén a tételek áfakulcsai nem különbözhetnek | On a final invoice with the simplified invoice image, the VAT rates of the items must match those of the prepayment invoice; the order of the items does not matter. See Simplified item data for tour operators. |
556 | Egyszerűsített számlaképet szállítólevél és helyesbítő számla esetén nem lehet használni | The simplified invoice image cannot be used for delivery notes and corrective invoices. See Simplified item data for tour operators. |
Next steps
- Session cookies: understand how session handling works and why it matters
- Sending requests: learn how to structure requests correctly to avoid errors
- Authentication: set up your Agent key