Errors

Every failed request returns a non-2xx status and a body of the same shape.

The error body

{
  "errors": [
    {
      "message": "toAmount has more decimal places than the settlement token supports.",
      "code": "INVALID_PAYMENT_LINK_AMOUNT"
    }
  ]
}

array

required

One or more error details.

Show properties

string

required

Human-readable description. For a schema 422, it describes the rule that failed, such as Field required — it does not name the field.

string

required

Stable machine-readable identifier. Branch on this, not on message.

Always read code, never message. Message text is written for humans and may be reworded; codes are stable.

Status codes

Status	Meaning	Retry?
`400`	Request refused as it stands — for example a keyed quote missing an address	No — change the request
`401`	Missing, invalid or expired key	No — fix the key
`403`	Key lacks the required scope	No — issue a key with the right agent
`404`	No payment link or transaction with that id, or an unknown token	No — check the id
`409`	The account is not set up for the operation	No — its owner has to act first
`422`	Request body failed validation	No — fix the request
`429`	Rate limit exceeded	Yes, with backoff
`500`	Unexpected server error	Yes, with backoff — but see the note below

Only 429 and 5xx are worth retrying. Retrying a 400, 401, 403, 409 or 422 will fail identically every time and will count against your rate limit.

Two 5xx codes are not worth retrying in a loop.CANNOT_CREATE_QUOTE is the catch-all for a quote that could not be built — an unknown token, an unroutable pair, a provider declining the route, a handle that belongs to nobody. None of those becomes true on a second attempt, and swaps in particular have many unroutable pairs. Retry it once, then stop and report which pair failed.CANNOT_PROCESS_EXISTING_TRANSACTION means the hash is already recorded in a way you cannot re-post — see below. Do not retry it at all.Every other 500 is worth ordinary backoff.

400 and 422 both mean “fix the request”, and the difference is where it was caught. A 422 came from schema validation — a field is the wrong type, missing, or out of bounds, and message describes the rule that failed. A 400 means the body parsed and every field was individually valid, but the request is refused as it stands: a keyed quote missing fromAddress or toAddress, an address on the wrong chain family for its chain id, a swap destination outside the key owner’s account, or an amount below the network’s minimum.The same code can arrive with either status — see the note under the Send and Swap table below.

Error codes

code is the stable identifier. Branch on it, never on message.

Every endpoint

`code`	Status	Meaning
`UNAUTHENTICATED`	`401`	No credential on a route that requires one. The Send and Swap quote, record and poll routes do not — without a key they run anonymously instead
`INVALID_API_KEY`	`401`	A key was sent, but it is unknown, revoked or deactivated
`EXPIRED_API_KEY`	`401`	The key is past its expiry — create a new one
`INSUFFICIENT_API_SCOPE`	`403`	The key does not hold the scope the endpoint needs
`429`	`429`	Rate limited. This one carries the status as its code

Payment links

`code`	Status	Meaning
`CANNOT_FIND_PAYMENT_LINK`	`404`	No link with that id
`PAYMENT_LINK_ACCOUNT_NOT_READY`	`409`	Owner has no default wallet, or no handle
`INVALID_PAYMENT_LINK_AMOUNT`	`422`	`toAmount` exceeds the settlement token’s decimal precision
`CANNOT_CREATE_PAYMENT_LINK`	`500`	Creation failed

Send and Swap

`code`	Status	Meaning
`INVALID_SOURCE`	`400` / `422`	`400`: a keyed quote omitted `fromAddress`; or, with or without a key, `fromAddress` is not of `fromChainId`’s chain family. `422`: a swap’s `fromAddress` does not parse as an address on any supported chain
`INVALID_DESTINATION`	`400` / `422`	`400`: a keyed quote (send or swap) omitted `toAddress`, or named a destination the key may not pay; or, with or without a key, `toAddress` is not of `toChainId`’s chain family (for a send to a handle, its owner’s default wallet). `422`: the address supplied does not parse — on a send, `toAddress` is neither a valid address nor a handle, or `fromAddress` does not parse
`UNOWNED_SWAP_DESTINATION`	`400`	A keyed swap’s `toAddress` is not a wallet on the key owner’s own account
`INVALID_SWAP_PAIR`	`400`	A keyed swap named the same token on the same chain — that is a transfer
`CANNOT_CREATE_SELF_QUOTE`	`400`	A send whose source and destination are the same wallet, chain and token
`SEND_AMOUNT_BELOW_MINIMUM`	`400`	A Bitcoin or Tron send below the network’s minimum. The `message` names the amount and symbol
`INSUFFICIENT_TOKEN_BALANCE`	`400`	A Bitcoin or Tron send the source wallet cannot cover, fees included
`CANNOT_FIND_TOKEN`	`404`	A Tron send whose source token is not in the catalogue. Resolve it from `/v1/token`
`CANNOT_FIND_TRANSACTION`	`404`	No transaction with that id
`SEND_ACCOUNT_NOT_READY`	`409`	`fromAddress` is not a signature-connected wallet of the key owner. Returned by a keyed quote (send or swap), before signing, and by the record call
`INVALID_TRANSACTION_PRODUCT`	`422`	Keyed `POST /v1/transaction` with a missing `product`, or one that is neither `"send"` nor `"swap"`
`CANNOT_CREATE_QUOTE`	`500`	The quote could not be built — an unknown token, an unroutable pair, or a handle that belongs to nobody. Retry once, then stop
`CANNOT_PROCESS_TRANSACTION`	`500`	Recording failed. Retry with backoff and the same body
`CANNOT_PROCESS_EXISTING_TRANSACTION`	`500`	That hash is already recorded — by another account, or as a different `product`. Do not retry

Two codes carry two statuses. The status says where the request was stopped: a 422 came from schema validation, so the value you sent is malformed; a 400 means every field parsed and the request is refused as it stands — a keyed rule, or an address on the wrong chain family. Branch on the pair, not on the code alone.

A malformed request body is also a 422, raised by request validation before any of the codes above. Its message describes the rule that failed and its code is not from this list — treat any unrecognised 422 as “fix the request”.

INVALID_API_KEY deliberately covers unknown, revoked and deactivated keys with one identical message. Distinguishing them would tell an attacker whether a guessed key ever existed. EXPIRED_API_KEY is separate because expiry is a state the legitimate owner needs to diagnose, and it reveals nothing to anyone who did not already hold the key.

The ones worth understanding

409 — the account is not set up for this operation

The key is valid and correctly scoped, but the account itself is not ready. It means one of two different things depending on the product, and neither is transient.Receiving: the owner has no default wallet, or no handle. They have to claim a Moove Handle and set a default wallet with a settlement token.Sending or swapping (SEND_ACCOUNT_NOT_READY): fromAddress is not a wallet the owner connected by signature. A receive-only address, added by pasting it into settings, cannot be the source of a send or a swap, because pasting an address is not proof that you hold its key. This is the single most common integration failure.With a key, POST /v1/quote/send and POST /v1/quote/swap both check this before you sign, so it normally arrives at the quote and nothing has moved. No amount of retrying will connect a wallet; the owner has to do it in the Moove App or the dashboard.

Getting it from POST /v1/transaction instead — because the wallet was disconnected between quote and record — is not a lost payment. That call only records; the funds moved on chain regardless. Reconnect the wallet, then record the same hash again. Do not re-broadcast, or you will send twice.

Surface it to the user rather than retrying.

400 — the request is refused as it stands

Three kinds of 400 reach a quote, and they differ in who they apply to.Rules for keyed callers only. The website and the Moove App are not subject to these; an agent is, because it has no person watching the screen to notice an address is wrong.

INVALID_SOURCE / INVALID_DESTINATION — an address the schema marks optional, because the logged-out website quotes without one, but which a key must supply. Left out, the quote would be built against a placeholder you do not control. INVALID_DESTINATION is also returned for a toAddress no keyed payout or swap may be sent to, such as a wallet moove.xyz operates itself.
UNOWNED_SWAP_DESTINATION — a swap returns its output to you, so its toAddress must be a wallet on your own account. To pay somebody else, use Moove Send.
INVALID_SWAP_PAIR — the same token on the same chain is a transfer, not a swap. Use POST /v1/quote/send.

A rule for every caller, with or without a key. Each address must be of its own leg’s chain family — EVM, SVM, TVM or BVM, read from the chain catalogue. A fromAddress that is not of fromChainId’s family returns INVALID_SOURCE, and a toAddress that is not of toChainId’s family returns INVALID_DESTINATION, with a message naming both families — which is how you tell it apart from a missing address. On a send, a handle is checked through the wallet it pays, its owner’s default wallet. A bridge across families is fine as long as each address matches its own chain.Rules for every send. CANNOT_CREATE_SELF_QUOTE (source, destination and token all identical), and on Bitcoin and Tron SEND_AMOUNT_BELOW_MINIMUM (below the network’s minimum, which the message names) and INSUFFICIENT_TOKEN_BALANCE.Every one is refused before you sign, so nothing has moved. None is retryable. The keyed ones are cheap to avoid: supply both addresses, and use the endpoint that matches what you are doing.

422 — validation

The request body did not match the schema. message describes the rule that failed.Common causes: toAmount missing or not greater than zero, description over 500 characters, maxUsage below 1, expirationDate not an ISO 8601 timestamp or not in the future.There is also one 422 that schema validation cannot catch: INVALID_PAYMENT_LINK_AMOUNT. toAmount is quantised to the settlement token’s decimals, and rejected if that changes the value — so 49.9999999 fails against a 6-decimal USDC wallet while 49.999999 succeeds. Trailing zeros are not significant, so 100.0000000 is fine.The limit belongs to the destination wallet’s token, not to your request. See toAmount.

422 INVALID_TRANSACTION_PRODUCT — send product

A keyed POST /v1/transaction must set product to "send" or "swap" — a bridge is "swap" too. The scope the request needs is derived from it, so a missing or unsupported value has no scope to check against and is rejected rather than defaulted — defaulting would pick a permission on your behalf.Anonymous callers may omit product; a key may not.

No 401 for a missing key on the Send and Swap routes

POST /v1/quote/send, POST /v1/quote/swap, POST /v1/transaction and GET /v1/transaction/{id} also serve callers with no credential, because the website and the Moove App use them logged out. A request to one of them without an X-API-Key header is not refused — it runs anonymously, with none of the key’s checks, nothing attributed to the key, and redacted record and poll responses. Only GET /v1/transaction answers a missing key with 401 UNAUTHENTICATED.An unset or empty key variable is the usual way to get there: curl drops a header whose value is empty. Check the key is set before the first call. A key that is sent and is invalid still fails with 401 INVALID_API_KEY or 401 EXPIRED_API_KEY — it never falls back to anonymous.

500 CANNOT_PROCESS_EXISTING_TRANSACTION — the hash is already recorded

With a key, re-posting the same body — the same hash and the same product — for a transaction your own account already recorded is not an error: it returns that transaction again, so a record call whose response you lost is safe to retry unchanged.This code means the hash is recorded by another account, was re-posted with a different product (a swap’s hash as "send", or the reverse), or was re-posted without a key. Retrying will not change it.

429 — rate limited

Limits apply per API key and per source IP, whichever is reached first. Back off exponentially with jitter.Rate Limits →

Handling errors

import time, httpx

def create_payment_link(client, payload, attempts=4):
    for attempt in range(attempts):
        r = client.post("/v1/payment-link", json=payload)
        if r.is_success:
            return r.json()
        if r.status_code not in (429, 500, 502, 503, 504):
            # Terminal. Retrying cannot help.
            raise RuntimeError(r.json()["errors"][0]["code"])
        time.sleep(2 ** attempt)
    raise RuntimeError("exhausted retries")

Rate Limits

What triggers a 429.

Authentication

401 and 403 in detail.

Moove Payment Links

The endpoints.

API Documentation

Moove Receive

Moove Send

Moove Swap

Coming Soon

The error body

Status codes

Error codes

Every endpoint

Payment links

Send and Swap

The ones worth understanding

Handling errors

Next

Rate Limits

Authentication

Moove Payment Links

​The error body

​Status codes

​Error codes

​Every endpoint

​Payment links

​Send and Swap

​The ones worth understanding

​Handling errors

​Next

Rate Limits

Authentication

Moove Payment Links

The error body

Status codes

Error codes

Every endpoint

Payment links

Send and Swap

The ones worth understanding

Handling errors

Next