Troubleshooting / FAQ

Every failure your integration can hit, what causes it, and what to do about it.

Two kinds of failure — check which one you have

API errors — qbill rejected the request. You get an HTTP error status, and the invoice was never sent to NRS.

Gateway rejections (NACKs) — qbill accepted and transmitted the invoice, and NRS refused it. You get HTTP 200 or 201; the invoice's status is rejected and it carries a plain-language reason and a corrective action.

API error codes

400Bad Request — validation failed

Cause	What to do
A required field is missing or malformed	The message field is an array of field-level messages; each names its field.
TIN format	Digits, optionally with one hyphen — e.g. 12345678-0001.
Currency	Use a 3-letter ISO code, e.g. NGN.
Invalid lifecycle transition	You attempted something the invoice's current status doesn't allow — see the lifecycle diagram on Key Concepts.

401Unauthorized

Cause	What to do
Missing x-api-key header	Generate a key in the dashboard under Developer Resources → API Keys.
Invalid or revoked API key	Keys are shown once at generation. If lost, revoke it and generate a new one.
Expired or invalidated session	Sign in again. Tokens are invalidated on password reset, suspension and removal.

403Forbidden

Cause	What to do
Not a member of the organisation	Check the organisation you're acting as.
Your role lacks the permission	Mutating endpoints require owner, admin or finance_manager. Viewers are read-only.
Organisation not verified	Complete business verification before configuring gateway credentials or transmitting.

404Not Found

Cause	What to do
The record doesn't exist, or belongs to another organisation	These are deliberately indistinguishable — a 404 isn't proof the record doesn't exist elsewhere.

409Conflict

Cause	What to do
Email already registered	Sign in, or reset the password.
Organisation already verified	No action needed — verification isn't repeatable.
Deleting an organisation that still holds invoices	Invoices are statutory records and can't be orphaned, so the organisation can't be deleted.

429Too Many Requests

Cause	What to do
A rate limit was exceeded	Back off and retry. For bulk work use the CSV upload endpoint — it submits many invoices in one request.

500Internal Server Error

Cause	What to do
Unexpected failure	Retry once. Don't resubmit an invoice repeatedly — it may have been accepted; check its status first.

Gateway rejections

qbill translates NRS's raw rejection text into a plain-language reason and a concrete corrective action. Text it doesn't recognise is passed through verbatim rather than replaced, so nothing is hidden or invented. Every attempt, including each rejection, is kept on the invoice's submission history — correcting and resubmitting never erases what was previously wrong.

Rejection	What it means	What to do
HSN code	Goods classification code missing or malformed (e.g. 0000.00).	Check each goods line item's HSN code against the NRS classification list.
ISIC code	Services classification code missing or malformed.	Check each service line item's ISIC code.
TIN format	The buyer's or seller's TIN isn't in an accepted format.	Digits with an optional hyphenated suffix, on both the seller and buyer records.
Duplicate IRN or invoice	NRS already holds an invoice with this reference.	Check for an existing cleared copy first — an earlier attempt may have succeeded.
Currency	Missing or invalid 3-letter currency code.	Set a valid ISO currency code.
Tax total, category or VAT rate	The tax breakdown doesn't match a category NRS recognises.	Review the rate and category per line item, especially zero-rated and exempt items.
Billing reference	The referenced original invoice couldn't be found.	Confirm the original cleared successfully before issuing a credit or debit note against it.
Required field missing	NRS names the missing field verbatim.	Fill it in and resubmit.
Rate limit	NRS is throttling submissions.	Wait a few minutes and resubmit unchanged.
Reporting deadline	A B2C invoice missed the statutory reporting window.	It can't be submitted as-is — issue a new invoice promptly.
Anything else	NRS's own text is shown verbatim, never replaced or hidden.	Review against the reason. If it repeats, contact support with the invoice number.