Moolre Documentation

Build and operate

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.

FieldWhereMeaning
errorOn failures{ code, message, fields: [{ field, code, message }] }. It lists every failing field, while the top-level code and message keep describing the first one.
metaEvery JSON response, always lastAn object with requestid and notices (and replayed on idempotent replays). It is always there, so you never need to check that it exists.
meta.requestidEvery JSON responseA unique id such as req_c68f4c66115c26725c796242. It is the same value as the X-Request-Id response header.
meta.replayedIdempotent replays onlytrue when the response is the stored answer to a repeated Idempotency-Key. Absent on every other response.
meta.noticesEvery JSON responseAlways 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_atTransaction rowsISO 8601 UTC time with Z, for example 2026-11-15T09:30:00Z. The older ts field is unchanged.
{  "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.

POST /open/transact/status HTTP/1.1Host: api.moolre.comX-Request-Id: order-1001-attempt-1​HTTP/1.1 200 OKX-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 statusWhen (strict mode)
200Success, and pending outcomes that are not errors
400A field is missing or invalid
401Authentication failed
403The credential or wallet is not allowed to do this (for example a public key on a private-key endpoint, or an inactive wallet)
404The wallet, transaction, batch, invoice or event was not found
409A duplicate: reused reference, or an Idempotency-Key reused with a different request (IDEM01)
422The request is well formed but cannot be processed (for example every bulk item was rejected)
429Too many one-time-code attempts (OTP429)
502 / 5xxAn upstream network or Moolre service problem. TP18 and PY02 mean the outcome is unknown, not failed
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.
{  "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 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"  }'