JoFotara Error Codes: Why an Invoice Is Rejected and How to Fix It

The invoice left your software, the response came back, and the screen says the request succeeded. But no QR code appeared on the invoice, and your customer is standing there waiting for a document they can actually rely on before the Income and Sales Tax Department.

That is the most expensive misunderstanding in the whole subject of JoFotara error codes: reading the HTTP status as if it were acceptance of the invoice. The HTTP status tells you the message arrived. The state of the invoice itself is a different thing entirely, and it is read from a different field in the response.

This guide is written for the people who actually run the connection: the business owner whose invoices keep bouncing, the accountant chasing the gaps, and the developer reading the response payload. It does not explain what the national system is, who is obliged to use it, or how to set the connection up in the first place. It starts at the moment your invoice was rejected and ends at the cause and the fix. Every code and message below comes from version 1.5 of the ISTD technical integration manual and from the official questions-and-answers guide.

Rule one: an invoice is not judged by its HTTP status

Before any diagnosis, fix the way you read the response. The technical manual is explicit here, and makes it the first of its operating instructions: the final state of the invoice is taken from EINV_STATUS, not from the HTTP status code.

The response carries several fields. Response Status Code is the technical result of the call. EINV_STATUS is the authoritative state of the invoice. EINV_MESSAGE carries the error detail or the rejection reason. Alongside them come EINV_QR, which carries the QR code, and EINV_SINGED_INVOICE, the signed invoice returned by the system.

Alongside them sits EINV_RESULTS, which carries the invoice status together with arrays for information, warnings and errors. One of the manual’s operating instructions is to log that detail internally while showing the end user a simplified message. The split is deliberate: counter staff need one sentence telling them what to do, while whoever diagnoses the problem later needs the full error text.

EINV_STATUS has three values, and each means something different operationally:

• SUBMITTED: the invoice is approved and the QR code has been returned in EINV_QR. This is the only state that means the invoice counts.
• ALREADY_SUBMITTED: the same invoice was sent again with the same ID and UUID, so the system returned the original QR code. This is not a fault. It is the documented way to recover a QR code you failed to store.
• NOT_SUBMITTED: the invoice is rejected. The HTTP status will not be 200, and the QR, UUID and invoice-number fields come back null.

The practical rule that follows: an invoice is not received and approved unless the QR code comes back in EINV_QR, and that code must be printed on the invoice the buyer receives. Any sales flow that prints before the code arrives produces a piece of paper that will not serve as a tax document.

The four error families: which one is yours

The technical manual documents four common errors, and each has a completely different family of causes. The usual first mistake in diagnosis is treating a connectivity failure as an invoice-data problem.

Telling the families apart is not a technical nicety, because each one is fixed somewhere else. Two of them have nothing to do with the invoice in front of you: authentication and connectivity. A third traces to fixed data in your company profile that repeats on every invoice. Only the fourth concerns the content of the invoice itself.

The manual sets a preventive rule ahead of all of this: validate totals, taxes, the taxpayer number, the buyer number and the mandatory fields before sending, which on its own cuts down 400 messages. It adds that the file must comply with UBL 2.1, and that any structural flaw rejects the invoice regardless of how correct its numbers are. It also asks for a unified time format, the issue date running year, month, day.

Use that table as a triage order. A 504 does not call for opening the invoice at all, a 403 does not call for reviewing fields, and a 500 starts from the company profile rather than the invoice lines. That ordering alone removes most of the search time.

Error 500: start from taxpayer identity, not from the invoice

A 500 is the most confusing code, because the name suggests a server fault while its documented causes sit in your own data.

What makes it more confusing is that its source is fixed data that does not change between invoices. The seller block travels with every invoice: country code, tax number, and the company name exactly as registered at the department. The income-source sequence travels with it too. If one is wrong, every invoice you send is rejected, not one in particular.

So a 500 on one invoice while the rest go through points at the one cause that varies between invoices: the tax rate on that invoice’s items. If the rejection is across the board, start from the company profile. Note also that the manual ties field-level messages to the 400 code alone and records none for a 500. So if no message points you at a field, that in itself is a signal to look outside the invoice. The manual documents these causes:

1. A wrong tax number. The number sent in the seller block must match the one registered at the department, and the seller name is likewise sent as registered there, not as you write it on your own stationery.
2. A wrong income-source sequence. Together with the tax number, this is one of the two causes the manual names first for this code. The income-source sequence is a mandatory field on every invoice submitted through the API, sent in the activity block. It is not a field that only concerns people issuing manually from the portal: anyone linking a system has one and selects it.
3. A tax percentage outside the list. The accepted general sales tax percentages are a closed set: 0, 1, 2, 3, 4, 5, 7, 8, 10 and 16. Anything outside it is a common cause of a 500, including rates produced by a rounding step in an automatic calculation.

Less commonly, a 500 can come from a wrong Client ID or Secret Key. So if your income-source sequence is right and your rates are inside the list, check the credentials before you open the invoice file.

A suggested check order: verify the tax number and seller name exactly as registered at the department, then the income-source sequence selected in your integration settings, then the tax rates applied to your items. Three steps before you touch a single invoice.

Error 403: credentials, not content

A 403 has one documented cause: the Client ID or the Secret Key is wrong. Both are generated from the device-linking service inside the national system, both are entirely your responsibility, and the manual places the full burden of any unauthorised use on the taxpayer.

What is worth noticing is that a 403 usually does not appear on linking day. It appears later. The recurring practical causes are a key copied with a trailing space, internal test values used in a live send, or credentials regenerated by a new linking without being updated in the software. Note also that nothing in the technical manual describes an official test environment for the national system, so do not build a procedure around one existing.

How those two keys are obtained is outside the scope of this guide; the full walkthrough is in how to connect your accounting system.

Error 504: the problem is the route, not the invoice

A 504 means the national system could not be reached, caused either by your firewall or by the site itself. Do not rebuild the invoice and do not change its fields in this state.

And because the invoice never arrived, there is no status to read and no QR code to wait for. This is the one case where silence is normal, and the invoice should not be recorded as rejected in your books.

The official instruction here is precise and matters a great deal: on a timeout or a connection failure, resend without generating a new UUID. Minting a fresh UUID on every attempt is what produces duplicate invoices, and the manual warns against it explicitly.

If you run a till or an online store, make this case part of a daily procedure rather than an exception: how invoices without a returned code are displayed, who resends them, and when. The store path specifically is covered in connecting an online store in Jordan.

Error 400: the validation messages and what each one means

A 400 is the most detailed and the easiest to fix, because the reason for rejection arrives written out in EINV_MESSAGE. The manual documents eight recurring messages, and a few of them are misspelled in the source itself, so do not assume you have misread them.

The buyer-name rule: when it becomes mandatory

Bayer name is missing confuses people because the name is not always required. The documented rule has two conditions: the buyer name is mandatory if the invoice is on credit terms, and mandatory as well if it is a cash invoice whose value exceeds 10,000 JOD or the equivalent in another currency. Outside those two cases the name is not required.

Alongside the name, the buyer phone is digits only and between 9 and 14 of them, the governorate is sent as a code such as JO-AM for Amman and JO-IR for Irbid, and the buyer identifier has a declared type: national number, personal number for non-Jordanians, or tax number.

The zero trap: S versus Z versus O

There are three tax categories and each carries a different legal meaning. S is taxable at a rate other than zero, Z is exempt, and O is zero-rated. The recurring mistake is sending a zero percentage with category S, which produces that message verbatim.

There is a broader case too. Export, development-zone, transit, foreign-trade and free-zone transfer invoices must have every line at zero percent with category O. A single line at another rate is enough to reject the invoice. The rates themselves are covered in general sales tax in Jordan.

Five rejection causes you would not suspect

Some rejections come from decisions that look purely accounting-side but collide with the invoice structure rules.

Most of them trace back to the totals formulas, which the manual fixes precisely and which leave no room for interpretation. The amount before tax is the sum of quantity times unit price across the lines. A line’s value is quantity times price minus the discount, and the tax is calculated on that post-discount value rather than the pre-discount one. The payable amount is the sum of the line values inclusive of their tax.

The moment your software’s calculation drifts past the permitted rounding tolerance, the totals message comes back. So the thing worth examining is the formula itself, not the invoice re-entered by hand. This matters more with special tax, which travels in a second, separate tax block, with general sales tax then calculated on the line value plus the special tax rather than on the line value alone. These are the most frequent in practice:

• An invoice-level discount. The system does not accept a discount applied to the invoice as a whole. If your software grants a total discount, it must distribute it across the lines before sending. A line discount is always sent as a positive value.
• Mixed currency inside one invoice. Currency is set for the whole invoice, never per line, with the dinar as the default alongside other supported currencies.
• A zero or negative quantity. Quantity must be greater than zero. Correcting with a negative line is not an accepted path, and the real path appears further down.
• Rounding outside tolerance. Rounding runs to three decimals, and the accepted difference does not exceed 0.001. Small accumulated differences from tax-inclusive pricing are a recurring source of the totals message.
• The invoice counter. Every invoice carries a counter starting at 1 and incrementing. When it drifts, the damage shows up late, as gaps that are hard to explain afterwards.

Note one distinction that many people miss: an income invoice carries no tax block at all, so its lines are quantity, price, discount and item name only. As for the authorisation message above, the manual ties it to a mismatch between the invoice type and your tax registration, not to the content of the lines.

ID and UUID: why your invoices duplicate

The key of an invoice is not its number alone. It is the number and the UUID together. The UUID is generated by your own system, and that is where the most expensive mistake lives.

If a send fails and your system mints a new UUID on the retry, you are not resending the same invoice. You are creating a second one. The manual warns about this specifically and makes resending with the same ID and UUID a standing instruction.

The second benefit of that rule is that it is how you recover a QR code you lost: resend with the same values, and the state comes back as ALREADY_SUBMITTED with the original code attached. This is why the manual recommends storing the invoice ID, UUID, QR code and status for every invoice, and keeping a full log of sends, responses and resends.

Pre-submission failures: when the account is the problem

Not every failure is technical. The official questions-and-answers guide documents a set of cases that sit before the invoice altogether, and they consume a great deal of time in real businesses.

Most of them revolve around a single distinction: the difference between the main user and the sub-user. The main user is the one who creates sub-users, and invoices are issued from the sub-user alone. A great many support questions come down to a business owner hunting for an option that simply does not appear on the screen they are standing on.

Two smaller details block registration at the very start: pop-ups must be enabled in the browser, and the password has its own rules, at least eight characters combining letters, numbers and symbols, with at least two letters one of which is a capital. The guide also records that a device linked by mistake is fixed the same way as a missing invoice-issuing option. These are the documented cases:

• “The account has been stopped, please contact the system administrator.” The official cause is a suspended sub-user, and the fix is to reactivate it from the main user.
• The national invoicing option does not appear in e-services. The cause is that the taxpayer file type is “users”, and the fix is to request a change of the file to “individuals”.
• Logging in to register returns you to the home page. The cause is the absence of an income-source sequence, and the fix is to add one. It is the same root cause that resurfaces later as a 500.
• The invoice-issuing option does not appear at all. Either you are on the main-user screen, or the device-linking option was clicked. Invoices are issued from the sub-user only.
• The verification code goes to the old phone number. Entering the password incorrectly leads to the phone number being updated.

These cases explain why it sometimes looks as though “the integration is broken” when the integration is fine and the account is what is blocked. If you are still checking whether the obligation applies to you at all, who must use e-invoicing in Jordan answers that, and you can measure your readiness with the readiness check.

An invoice was rejected after the customer already had it

This is where people ask about editing, and the answer is that an issued invoice cannot be edited. Version 1.5 of the technical manual defines two document types only: a new invoice and a return invoice, the latter being a credit note. It defines no debit note.

The practical path therefore runs through the return invoice, which works on quantities only, cannot exceed the quantity sold on the original, and requires a stated reason. The limits of editing are covered in editing an issued invoice.

A return invoice has requirements of its own: it must reference the original invoice by number, UUID and total value, and the reason must be stated in text. Several partial returns against one original are allowed until the sold quantities are exhausted.

And because returns are matched to lines by their IDs, failing to store the line ID from the original sale becomes a problem on the day of the return rather than the day of the sale.

Ten minutes to diagnose any rejection

This is a check order a non-technical member of staff can run before escalating. It rests on one principle: check the cheapest thing first, meaning whatever can be ruled out at a glance before anything that requires opening the invoice and reading its lines.

Before starting, keep the full text of the response. The manual recommends storing the invoice ID, UUID, QR code and status for every invoice, and keeping a detailed log of sends, responses and resends. Without that you diagnose from scratch every time, and you lose the ability to tell whether a rejection is a repeat or a new one.

Note that the order below tests families before fields. Testing one family takes seconds and rules a quarter of the possibilities in or out at once, while testing a single field takes minutes and may rule out nothing. The first four steps settle the family; the remaining six examine the fields that belong to the content family alone.

1. Read EINV_STATUS first, never the HTTP status. If it says ALREADY_SUBMITTED, the invoice was already accepted and the code has come back to you.
2. If the code is 504, the fault is connectivity. Resend later with the same ID and UUID.
3. If it is 403, check the stored Client ID and Secret Key before anything else.
4. If it is 500, check in this order: tax number, then income-source sequence, then the applied tax percentage.
5. If it is 400, read EINV_MESSAGE literally and match it against the message table above.
6. Check the invoice type against your tax registration: income invoice or general sales tax invoice.
7. Check the buyer name against the credit-terms rule and the 10,000 JOD rule.
8. Check for an invoice-level discount that was never distributed across the lines.
9. Check that line IDs are unique within the invoice.
10. Record the full status and message before any new attempt. The message is your only evidence if the rejection repeats.

If the same pattern repeats across many invoices, the fault is a setting and not an invoice. Review company settings, items and tax rates once, instead of handling each invoice separately. And if you are still weighing manual issuing against issuing from an accounting system, that trade-off is covered in the free portal or an accounting system.

How Qoyod reduces these errors

Qoyod is integrated with JoFotara, and the part that matters here is the shape of the flow: the invoice is built once inside your accounting system and sent from there, with no re-entry in the portal and no second copy of the data.

Go back to the four error families above and you will find that three of them do not live in the invoice at all. They live in fixed data that repeats with every invoice: the tax number, the income-source sequence, and the item’s tax rate. Each is set once, then reused.

That is the practical difference between handling rejections invoice by invoice and handling them once, where they originate. What follows is not a promise that no invoice is ever rejected, since the rules are the department’s, but it reduces the number of places an error can leak in. One measure applies to any system: how many places you set by hand before an invoice comes out correct, and how often.

• A Jordanian tax engine. General sales tax at 16% with the reduced rates and the exempt and zero-rated logic, labelled in the product as general sales tax at 16%. The rates you work from are therefore the Jordanian ones, which is where a percentage outside the approved list usually creeps in.
• A Jordanian tax-invoice template. It carries the tax number, runs bilingually in Arabic and English, prints the QR code returned by the national system, and covers the mandatory fields.
• The four document types. Income invoice, general sales tax invoice, special tax invoice, and return invoice as a credit note, matching what the technical manual defines.
• The Jordanian dinar for invoicing and formatting, with multi-currency support in the books.
• Excel import with a per-row error report emailed back, and every attempt logged in the activity report. This matters specifically when loading items or opening balances in bulk, which is where a lot of later data errors begin.
• User permissions and multi-branch management to control who issues and who approves, with reports to track what was actually issued.
• A mobile app, an API and Zapier for anyone arriving from an online store or another tool, along the path: platform, then Zapier or the API, then Qoyod, then the national system.
• Operating experience under a comparable mandate. More than 25,000 businesses run on Qoyod in the Saudi market under a comparable e-invoicing mandate. That is operating experience under a mandate, now carried across to Jordanian requirements.

For an accountant handling several clients, the integration page for accounting firms covers that side, while the compliance page for business owners shows the same picture from the owner’s seat. The wider offering sits on Qoyod in Jordan.

Frequently asked questions

I got a 200 but the invoice has no QR code. Is it approved?

No. The HTTP status only means the request was processed technically. The invoice is judged from EINV_STATUS, and it does not count as received and approved unless the QR code comes back in EINV_QR. That code must then be printed on the invoice.

What is the most common cause of a 500?

The technical manual names a wrong tax number or a wrong income-source sequence as the leading cause, then wrong credentials less often, then a tax percentage outside the approved list. Start from the company data and the income-source sequence before you open the invoice.

I resent an invoice and it duplicated. What went wrong?

Most likely your system generated a new UUID on the retry. The key of an invoice is its ID and UUID together, and a resend must use both unchanged. Done that way, the state comes back as ALREADY_SUBMITTED with the original QR code instead of a second invoice.

How do I tell a connectivity fault from an invoice-data fault?

A 504 means the system could not be reached, caused by your firewall or by the site itself. In that case do not modify the invoice at all; resend later with the same ID and UUID.

When is the buyer name mandatory?

The buyer name is mandatory on every credit-terms invoice, and also on a cash invoice whose value exceeds 10,000 JOD or the equivalent. A missing name in either case produces an explicit rejection message under a 400.

My tax is zero but the invoice is rejected. Why?

Because the tax category is most likely set to S while the percentage is zero. A zero rate requires category O, and an exempt line requires Z. On export, development-zone, transit, foreign-trade and free-zone transfer invoices, every line must be at zero percent with category O.

Can I edit a rejected invoice after the customer has it?

An issued invoice cannot be edited. Version 1.5 of the technical manual defines two types only: a new invoice and a return invoice, which is a credit note. Corrections are made with a return invoice, on quantities only, never exceeding the quantity sold on the original, and with a stated reason.

How do I check that an invoice I received from a supplier is genuine?

Scan the QR code with the Sanad app under the digital-document verification option. The app states whether the document is valid and displays the basic invoice data carried inside the code. The detail is in verifying an e-invoice with the Sanad app.

The takeaway

Most rejections in the national system are not faults. They are precise messages pointing at a specific field. The difference between clearing a rejection in minutes and spending days on it is the reading order: status before HTTP code, message before guesswork, and company data before invoice lines.

Three habits close most of this door. Store the invoice ID, UUID, QR code and status for every invoice. Always resend with the same ID and UUID. Review tax rates and categories at the item level once, rather than invoice by invoice.

Start today with one step: open your last ten rejected invoices and write the literal message returned for each. You will most likely find that three messages explain all ten, and that fixing a single setting closes more than half of them. If you are building the integration from the accounting side, the e-invoicing requirements in Jordan completes the mandatory-field picture, while Jordan’s national e-invoicing system covers the system as a whole.