Response codes & errors

8.1 Two layers of result

Every response has two results, and you need both:

1. The HTTP status: did the request reach InnBucks and get processed?
2. The JSON responseCode: did the operation succeed?

HTTP 2xx + responseCode "00"  → success (for linked account inquiry: "000")
HTTP 2xx + any other code     → the operation failed: read responseMsg / responseDescription
HTTP 401                      → token expired or invalid: log in again, retry once
HTTP 4xx (other)              → your request is wrong: fix it, don't retry as-is
HTTP 5xx / timeout            → unknown outcome at InnBucks: see 8.3

For code inquiries, a successful responseCode only means the inquiry worked. Whether the customer paid is in status.

8.2 Response codes

Code	Meaning	Where
00	Approved or completed successfully	All endpoints except linked account inquiry
000	Approved or completed successfully	Linked account inquiry
025	Unable to locate original request, or already processed	Reversal
096	Request failed, please try again later	Reversal
Anything else	Failed. The reason is in responseMsg or responseDescription	All endpoints

InnBucks publishes the complete, current list at GET {baseUrl}/api/file/response-codes (7.12). Treat every code that is not 00 (or 000) as a failure, show your user a friendly message, and log the code, the message and the X-Trace-Id.

A helper that works for every endpoint:

ok(response)      = response.responseCode in {"00", "000"}
message(response) = response.responseMsg ?? response.responseDescription

8.3 What to retry

Situation	Retry?	How
401	Once	After logging in again (4.2)
Code inquiry fails or times out	Yes	At the next 30-second check
Generate code times out	Yes, carefully	Generate a new code, but keep checking the first one if you got its code (5.5)
Deposit times out or returns 5xx	No	Run a deposit inquiry with the same reference (6.3)
Bank change or utility payment times out	No	Check your statement or contact InnBucks with the X-Trace-Id before trying again
Reversal returns 096	Yes, later	Ask InnBucks whether to reuse the participantReference; check with a deposit inquiry first
Any other 4xx, or a non-00 code	No	Fix the request; it will fail the same way again

The rule behind the table: never re-send a request that moves money until you know the first one failed. It may have succeeded after your side gave up.

8.4 Logging

For every call, log the endpoint, your reference, the responseCode, the message, the HTTP status and the X-Trace-Id response header. Never log the password, the API key or the access token. When you contact InnBucks about a request, send its X-Trace-Id: it is how they find it.

---

This page is generated from section 8 of the README in README.md. Spotted something wrong? Open an issue.