Errors & Status Codes¶

Error envelope¶

Confirmed error responses share a consistent shape:

{
    "success": false,
    "message": "<human-readable description>"
}

success: false combined with a non-2xx HTTP status code is the reliable way to detect an error — check the status code first, then read message for detail.

Confirmed examples¶

HTTP Status	`message`	Endpoint observed on	Cause
`401`	`Invalid username/password.`	`GET /auth/token/`	Wrong client ID/secret in Basic Auth
`401`	`Authentication credentials were not provided.`	`POST /payments/initiate/`, `GET /merchants/wallets/`	Missing, invalid, or expired Bearer token — despite the message, this was also observed for an expired token, not only a missing one
`403`	`Your IP address is not whitelisted.`	`POST /payments/status-query/`	Calling IP isn't on the application's whitelist — see IP Whitelisting

Unconfirmed: other status codes¶

HTTP Status	Meaning	Likely cause
`400`	Bad Request	Validation error — a required or conditional field (see Initiate Payment) is missing or malformed
`404`	Not Found	The endpoint path or referenced resource (e.g. a transaction reference) doesn't exist
`429`	Too Many Requests	Rate limit exceeded — back off and retry
`5xx`	Server Error	An error on Hivemind Payments' side — retry with backoff; contact Hivemind Payments support if persistent

Handling errors¶

Treat 401 as a signal to re-authenticate rather than retry the same request unchanged — note it's used for both "no token" and "expired token", so you can't distinguish those cases from message alone.
Treat 403 with the IP-whitelist message as an infrastructure problem (your egress IP changed or isn't registered yet), not a request bug — retrying the same request from the same IP won't help.
Log the full response body for non-2xx responses during integration — beyond the two confirmed codes above, the exact schema for other error types is still unconfirmed.