Responses, request IDs and notices
Environment: Live
How to read any response, quote a request to support, act on notices, debug a failure and opt in to real HTTP status codes.
# Responses, request IDs and notices
How to read any response, quote a request to support, act on notices, debug a failure and opt in to real HTTP status codes.
## The response envelope
Every response is a JSON object with status, code, message, data and go. These fields, their order and their types are unchanged. New information is only ever added as extra fields, so a client written against the older responses keeps working. The request id and the notices live in the meta object, which is the last field of every JSON response.
Webhook payloads are different: they keep event_id, event and created at the top level and carry their notices in meta.notices (they have no requestid). See Webhooks and callbacks.
| Field | Where | Meaning |
| --- | --- | --- |
| error | On failures | { code, message, fields: [{ field, code, message }] }. It lists every failing field, while the top-level code and message keep describing the first one. |
| meta | Every JSON response, always last | An object with requestid and notices (and replayed on idempotent replays). It is always there, so you never need to check that it exists. |
| meta.requestid | Every JSON response | A unique id such as req_c68f4c66115c26725c796242. It is the same value as the X-Request-Id response header. |
| meta.replayed | Idempotent replays only | true when the response is the stored answer to a repeated Idempotency-Key. Absent on every other response. |
| meta.notices | Every JSON response | Always an array, empty when there is nothing to report. Each notice is { code, message, docs? }, for example that a deprecated way of sending credentials was used. See Deprecations. |
| created_at | Transaction rows | ISO 8601 UTC time with Z, for example 2026-11-15T09:30:00Z. The older ts field is unchanged. |
```json
{
"status": 1,
"code": "SS02",
"message": "Transaction Failed",
"data": {
"txstatus": 2,
"txtype": 1,
"accountnumber": "10657506045981",
"payer": "233552991926",
"payee": "",
"amount": "0.00",
"value": "0.00",
"fee": "0.00",
"networkfee": "0.00",
"transactionid": "",
"externalref": "OP-0e6a3c38-b39d-48d2-9d3a-60dd083039a3",
"thirdpartyref": "",
"ts": "2025-06-17 03:47:49",
"created_at": "2025-06-17T03:47:49Z"
},
"go": null,
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": [
{
"code": "PUBKEY_RESIGN",
"message": "This public key was signed with a retiring key; generate a new public key before 2030-12-31.",
"docs": "https://docs.moolre.com/guides/authentication"
}
]
}
}
```
## Request IDs
Quote meta.requestid whenever you contact support: it identifies exactly one request in Moolre's logs. Log it next to your own order or payout reference.
You can supply your own id with the X-Request-Id request header (8 to 64 characters from A-Z a-z 0-9 . _ -). Moolre then uses it as meta.requestid and echoes it back in the X-Request-Id header, which lets you correlate a request across your own systems. Anything else is replaced with a generated id.
```http
POST /open/transact/status HTTP/1.1
Host: api.moolre.com
X-Request-Id: order-1001-attempt-1
HTTP/1.1 200 OK
X-Request-Id: order-1001-attempt-1
```
## Real HTTP status codes (opt-in)
By default Moolre answers HTTP 200 for application-level failures and puts the outcome in status and code, exactly as before. If you prefer standard HTTP semantics, send the request header X-Moolre-Http-Status: strict. Nothing else changes in the body.
Without the header the behaviour is identical to before, so you can adopt strict mode one integration at a time.
| HTTP status | When (strict mode) |
| --- | --- |
| 200 | Success, and pending outcomes that are not errors |
| 400 | A field is missing or invalid |
| 401 | Authentication failed |
| 403 | The credential or wallet is not allowed to do this (for example a public key on a private-key endpoint, or an inactive wallet) |
| 404 | The wallet, transaction, batch, invoice or event was not found |
| 409 | A duplicate: reused reference, or an Idempotency-Key reused with a different request (IDEM01) |
| 422 | The request is well formed but cannot be processed (for example every bulk item was rejected) |
| 429 | Too many one-time-code attempts (OTP429) |
| 502 / 5xx | An upstream network or Moolre service problem. TP18 and PY02 mean the outcome is unknown, not failed |
```curl
curl https://api.moolre.com/open/transact/status \
-H "Content-Type: application/json" \
-H "X-API-USER: $MOOLRE_USER" -H "X-API-KEY: $MOOLRE_KEY" \
-H "X-Moolre-Http-Status: strict" \
-d '{"type":1,"idtype":1,"id":"ORDER-1001","accountnumber":"1000000000001"}'
```
> **A 5xx or timeout is not a failed payment:** When a collection or payout times out, the money may still move. Never create a new reference and resend. Check Payment Status or Transfer Status with the original reference, or wait for the webhook.
## Timestamps and amounts
created_at and the other new time fields are ISO 8601 in UTC with a trailing Z. Existing ts fields keep their format.
Money values stay the strings or numbers each endpoint has always returned. New endpoints (bulk payouts and invoices) return money as decimal strings with two decimals, for example "150.00".
## Step by step: read any response
1. Read the HTTP status first. In the default mode it is 200 even for application errors; in strict mode it is the real status (400, 401, 403, 404, 409, 422, 429, 5xx). A timeout or a 5xx means you do not know the outcome.
2. Read status: 1 is success, 0 is failure. On some endpoints it is the string "1" or "0": compare loosely, or convert, but do not rely on the type.
3. Read code. It is the stable value for branching and logging. Use message as context for people, not for logic.
4. On a failure read error.fields: it lists every field that failed, each with its own code and message, so you can fix all of them in one go.
5. Decide the result from status, code and data.txstatus (0 pending, 1 succeeded, 2 failed). There is no outcome field. These codes mean unknown, may still succeed: PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06 and SYS500. Treat them as pending and check the status; never resend blindly. Status 1 with TR08, OBGH01, OTGH01, OBNG01, GHQ03 or OM03 is final success; any other status 1 is an accepted, unfinished request.
6. Read meta.notices (always an array). If it has entries, log them once per code and schedule the fix; they are advice, not errors.
7. Always log meta.requestid next to your own reference.
```jsonfailure
{
"status": 0,
"code": "APY07",
"message": "Request Parameters Incomplete, Please check and try again.",
"data": "amount",
"go": null,
"error": {
"code": "APY07",
"message": "Request Parameters Incomplete, Please check and try again.",
"fields": [
{
"field": "amount",
"code": "APY01",
"message": "Amount is required"
},
{
"field": "receiver",
"code": "APY06",
"message": "Recipient Details are required"
}
]
},
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}
```
## Step by step: debug a failed request
1. Find the meta.requestid of the failing call in your logs. If you did not log it, repeat the call and capture it; the X-Request-Id response header carries the same value.
2. Look the code up in Errors and status codes. Each code says what caused it and what to do.
3. If the code is an authentication one (AIN*), check the user, the key type for this endpoint, the environment and the wallet.
4. If error.fields lists fields, fix each one. Fix them all before you try again.
5. If the result is unknown (TP18, PY02, PY01, TR01, TR02, TP11, APY10, APY16, ASL06, SYS500, a timeout, a 5xx), do not repeat the request: check the status by externalref.
6. Still stuck? Contact support with the meta.requestid, the externalref, the time and the environment. They can find the exact request.
> **Send your own request id:** Set X-Request-Id on a request (8 to 64 characters from A-Z a-z 0-9 . _ -) and Moolre uses it as meta.requestid and echoes it back in the X-Request-Id header. Use your own order or job id and you can find any request from either side.
## Step by step: adopt strict HTTP status
1. Pick one integration or one environment (the sandbox is ideal) and add the header X-Moolre-Http-Status: strict to every request.
2. Change your HTTP client so that 4xx and 5xx are not thrown away: read the JSON body for 4xx too, because code and error are still there.
3. Map the statuses: 400 fix the request, 401 or 403 fix credentials or permissions, 404 not found, 409 duplicate or Idempotency-Key reuse, 422 well formed but not processable, 429 slow down, 502 or 5xx unknown outcome.
4. Keep treating 5xx, 502 and timeouts on money requests as unknown, never as failed.
5. Roll it out to the other environments once the sandbox is clean.
```curl
curl https://api.moolre.com/open/transact/status \
-H "Content-Type: application/json" \
-H "X-API-USER: $MOOLRE_USER" \
-H "X-API-KEY: $MOOLRE_KEY" \
-H "X-Moolre-Http-Status: strict" \
-d '{
"type": 1,
"idtype": 1,
"id": "ORDER-1001",
"accountnumber": "1000000000001"
}'
```
```jsonhttp
{
"status": 0,
"code": "SS07",
"message": "Transaction not found",
"data": "id",
"go": null,
"error": {
"code": "SS07",
"message": "Transaction not found",
"fields": [
{
"field": "id",
"code": "SS07",
"message": "Transaction not found"
}
]
},
"meta": {
"requestid": "req_c68f4c66115c26725c796242",
"notices": []
}
}
```
## Checklist and related guides
- [ ] You log meta.requestid on every call.
- [ ] You branch on status, code and data.txstatus, not on message text.
- [ ] You treat the unknown codes (PY01, PY02, TR01, TR02, TP11, TP18, APY10, APY16, ASL06, SYS500) as pending and check status instead of resending.
- [ ] You act on meta.notices before they become problems.
- [Errors and status codes](https://docs.moolre.com/guides/errors-and-status-codes)
- [Deprecations](https://docs.moolre.com/guides/deprecations)
- [Idempotency and external references](https://docs.moolre.com/guides/idempotency-and-references)
- [Pagination](https://docs.moolre.com/guides/pagination)