Errors & codes

Response shapes

Operation	JSON shape
Create (async or sync)	`status`, `response_code`, `response_message`, `data`
Status	`state`, `code`, `message`, `payload`
List	`state`, `result.items`, `result.page_info`
Wallet balance	`state`, `result.wallets`, `result.total`
Bill validate / packages	`state`, `result`
Bill status	`state`, `code`, `message`, `payload`

Transaction codes

On status, outcomes map to code / state:

`code`	`state`	Meaning
`00`	`success`	Successful
`01`	`failed`	Failed
`02`	`pending`	Still processing

Failed example (status):


{
  "state": "failed",
  "code": "01",
  "message": "Failed",
  "payload": {
    "request_id": "subthingy-req-20260517-001",
    "internal_reference": "019262ab-7c4d-7000-8000-000000000001"
  }
}

On async create, pending is returned immediately with HTTP 200 (not 202):


{
  "status": "pending",
  "response_code": "02",
  "response_message": "Pending",
  "data": { }
}

HTTP status codes

Status	When
`200`	Success (including async create with pending body)
`400`	Invalid JSON or validation error
`401`	Missing or invalid API key / secret
`403`	Credential cannot access this resource
`404`	Merchant or transaction not found
`422`	Duplicate request reference or missing required field
`500`	Server error — retry with backoff
`503`	Temporary overload (database semaphore) — retry with backoff

Health check


GET /v1/healthz

No authentication required.