Docs · Resources

Errors

Canonical catalog of error codes returned across the miaPOS API surface. Stable identifiers, human messages, suggested actions.

AudienceDeveloper

DifficultyBasic

Updated2026-05-30

Error envelope

Every error response uses the same shape:

{
  "error": {
    "code":      "INVALID_SIGNATURE",
    "message":   "Callback signature did not match the published public key.",
    "requestId": "req_01HZP2K7..."
  }
}

Match on code (stable across versions). message is for human display; requestId is for support tickets.

Catalog

Code	HTTP	Meaning
`INVALID_TOKEN`	401	Access token missing or malformed.
`TOKEN_EXPIRED`	401	Refresh via `POST /token/refresh`.
`INVALID_AMOUNT`	400	Amount not a positive decimal or exceeds merchant limit.
`INVALID_CURRENCY`	400	Currency not enabled for this merchant.
`UNKNOWN_PAYMENT`	404	No payment with that id, or wrong merchant.
`PAYMENT_ALREADY_COMPLETED`	409	Operation not allowed in current state.
`INVALID_SIGNATURE`	400	Callback signature mismatch — refetch public key.
`MERCHANT_DISABLED`	403	Merchant account suspended.
`TERMINAL_INACTIVE`	403	Terminal not activated or revoked.
`RATE_LIMITED`	429	Backoff and retry — see `Retry-After`.
`RAIL_UNAVAILABLE`	503	Underlying instant-payment rail down. Retry with backoff.