Gozem Developer DocsDocs
Back to siteGo to consoleConsoleGet beta accessGet access
Money API

Errors

This page lists the error codes specific to the Money API. Authentication and the shared platform codes (such as unauthenticated, forbidden, validation_failed, and rate_limit_exceeded) are documented in Authentication and API Basics. The codes below are in addition to those.

Error envelope

The transaction details and account endpoints use the same { "success", "message", "error_code" } envelope, but with lowercase snake-case codes — their codes are listed in their own table below.

The charge and payout endpoints still return failures with the legacy machine-readable error_code:

{
  "success": false,
  "error_code": "INSUFFICIENT_FUNDS",
  "message": "Payout amount exceeds the available balance.",
  "details": {}
}

Some errors carry extra fields alongside details: INSUFFICIENT_FUNDS includes available_balance, and LIMIT_EXCEEDED includes the relevant limit fields (min_amount, max_amount, daily_cap, monthly_cap, velocity_limit, …).

Branch on error_code, not on message. details is optional and carries validation or contextual data when present.

Charge and payout error codes

These are part of the public contract: new codes may be added over time, but existing rows never change meaning. Handle a code you do not recognize gracefully rather than failing hard.

Code HTTP When it occurs
VALIDATION_ERROR 400 The request body or parameters failed validation. details names the fields.
CHANNEL_NOT_SUPPORTED 400 The channel value is not in the supported list.
PAYER_NOT_ELIGIBLE 400 The payer exists but cannot be charged (charge).
BENEFICIARY_NOT_ELIGIBLE 400 The beneficiary exists but cannot receive funds (payout).
MERCHANT_ACCOUNT_NOT_CONFIGURED 400 The merchant has no primary Gozem Money wallet configured.
MERCHANT_PROFILE_INCOMPLETE 400 Required merchant fields (unique_id, wallet number) are missing.
INSUFFICIENT_FUNDS 402 The payout amount exceeds the available balance.
SEC_ENDPOINT_NOT_AUTHORIZED 403 The client is not entitled to this endpoint’s slug, or not linked to a merchant account.
LIMIT_EXCEEDED 403 A payout limit was breached: min/max amount, daily or monthly cap, or velocity (20 payouts per 5 minutes).
MERCHANT_NOT_RESOLVED 403 The merchant profile could not be loaded for this client.
PAYER_NOT_FOUND 404 The payer could not be resolved (charge).
BENEFICIARY_NOT_FOUND 404 The beneficiary could not be resolved (payout).
CHARGE_NOT_FOUND 404 The charge is unknown, or not owned by this client.
PAYOUT_NOT_FOUND 404 The payout is unknown, or not owned by this client.
ACCOUNT_NOT_FOUND 404 The charge or payout was not found, or is not visible to this client.
IDEMPOTENCY_CONFLICT 409 The same idempotency-key was reused with a different body (see Authentication).
UPSTREAM_ERROR 502 Gozem could not complete the call. Safe to retry with backoff.
PROVIDER_UNAVAILABLE 503 The PSP provider is temporarily unavailable. Safe to retry with backoff.

A plain 401 surfaces for a missing or invalid JWT, HMAC signature, or timestamp, and 500 INTERNAL_ERROR for unexpected failures.

Transaction details and account error codes

GET /money/v1/transaction-details/:id and GET /money/v1/account return the standard failure envelope — branch on error_code:

{
  "success": false,
  "message": "No transaction details found for this API client.",
  "error_code": "transaction_not_found"
}

Authentication and routing failures on these endpoints use the same shape with platform codes: 401 unauthenticated (missing or invalid token, bad signature, or a timestamp outside the 300-second window), 403 forbidden (the client is not entitled to the route’s slug), and 404 not_found (no such route).

Code HTTP When it occurs
merchant_account_not_configured 400 The merchant has no primary Gozem Money wallet configured.
merchant_profile_incomplete 400 Required merchant fields (unique_id, wallet number) are missing.
merchant_not_linked 403 The client is not linked to a merchant account.
merchant_not_resolved 403 The merchant profile could not be loaded for this client.
transaction_not_found 404 The transaction was not found, or your client is neither payer nor payee.
account_not_found 404 Wallet details could not be retrieved for this merchant.
service_unavailable 502 Gozem could not load the data upstream. Safe to retry with backoff.

Retrying

Treat 4xx as a problem with the request — fix the payload, payer, account, or idempotency condition named by the code rather than resending. The retryable cases are UPSTREAM_ERROR (502), service_unavailable (502), PROVIDER_UNAVAILABLE (503), and rate_limit_exceeded (429, see API Basics); retry those with exponential backoff rather than immediately.

A note on the bank error shapes

The Bank API (distributor balance, fund creation, and fund destruction) uses the same { success, message, error_code } failure envelope, with lowercase snake-case codes such as request_not_found and request_state_conflict. Its approve and cancel acknowledgements add a request_id, and carry error_code only when success is false. This page covers the merchant-facing Money endpoints only.