Operate

Errors

One error shape, and what each status code means.

Error response

{ "detail": "Human-readable error message" }

Status	Meaning
`400`	Bad request
`401`	Missing or invalid API key
`403`	Action not permitted (e.g. method not enabled)
`404`	Resource not found
`409`	Idempotency conflict
`422`	Validation error
`502`	Upstream provider error
`503`	Service temporarily unavailable, including rate-limit load shedding

How to handle each class#

Class	Retry?	What to do
`400`, `422`	No	Fix the request. Retrying an invalid body will not help.
`401`, `403`	No	Check the key and whether the method is enabled on your account.
`409`	No	You reused an idempotency key with a different body. Look up the original transaction.
`502`, `503`	Yes	Back off with exponential jitter and retry with the same idempotency key. A `503` also covers load shedding, so treat it as "slow down".

Retry with the same key. When you retry after a 5xx or a timeout, reuse the original idempotency key. That is what makes the retry safe.

A failed transaction is not an error. A payment that reaches failed returned 202 at creation. Read failure_reason on the transaction rather than expecting an HTTP error.

Reading failure_reason#

failure_reason is human-readable text describing why a transaction failed. Log it and surface it to your operators and support staff. Do not branch application logic on its exact wording, because the text may change. Where you need to react to a specific cause in code, react to the transaction reaching failed and drive follow-up from your own retry policy rather than from string matching.

Maly Payments API v1 · Documentation 1.1 · July 2026
Maly Tech Ltd. This guide is provided for information. Where it differs from your signed agreement, the agreement applies.