The response envelope, explained

Open the A8 Core™ API reference to any operation and you will notice the response always begins the same way: a RequestId, a Status, and then whatever the operation produced. It looks unremarkable. It is, in fact, the most important design decision in the API, because it draws a hard line between two questions that most APIs blur together: did the request reach us and get answered, and did the operation succeed.

Two failure modes, two channels

A network timeout is not the same kind of event as a rejected deposit, yet many APIs report both as an HTTP error and leave you to guess which happened. A8 Core™ keeps them separate. Transport, authentication, and signature problems return a non-2xx HTTP status — the request never became an operation. Anything we understood and answered returns HTTP 200 with a Status field: 1 for pass, 0 for a handled failure carrying a ResponseStatus that explains itself.

"RequestId": 1736472902501,
"Status": 0,
"ResponseStatus": { "ErrorCode": "ClientNotFound", "Message": "No client matches the supplied ClientId." }

The practical payoff is that your error handling has a clean shape. A non-2xx is a transport problem you retry. A Status: 0 is a business problem you read and act on. You never have to parse a stack of HTTP codes to figure out which world you are in.

RequestId is an audit primitive, not a debug aid

The RequestId is a 13-digit identifier minted for every call. It is tempting to treat it as a support convenience — quote it in a ticket and move on — but it is doing real work. It is the join key between your logs and ours. Because every state-changing directive is written to A8 Core™’s immutable evidentiary record keyed by the same identifier, the RequestId you captured at call time is also the thread an examiner can pull years later to see exactly what happened.

Log the RequestId on every response. It is the cheapest insurance you will ever buy in a regulated system.

Idempotency lives next to the envelope

The envelope tells you the outcome; ProviderReferenceId guarantees you only get that outcome once. Send a stable reference on every create and money-movement call and A8 Core™ treats a repeat from your provider as the same operation. A retried fund request never double-posts; a retried accounts request never opens a duplicate. The reference is yours to choose, scoped to you, and it is the single most effective bug-prevention habit in the entire integration.

A robust call, in practice

• Send the request with a stable ProviderReferenceId.
• On a non-2xx or timeout, retry with the same reference and exponential backoff.
• On 200, check Status; if 0, read ResponseStatus.ErrorCode and decide — fix and resend, or surface to the user.
• Persist the RequestId alongside your own record of the action.

Why this is a contract

APIs that lean only on HTTP semantics force every integrator to reinvent the same retry-and-classify logic, usually subtly wrong. By making the envelope explicit, A8 Core™ turns that logic into a contract: the same four fields, the same meaning, on every operation from CreateClient to Transact. Learn it once and the whole surface area becomes predictable.

That predictability is the point. Financial infrastructure is judged less on its best day than on its worst — the timeout, the duplicate, the dispute. The envelope is what makes the worst day boring.