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?
`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 with that id	No — check the id
`409`	The account is not set up to receive payments	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

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

Error codes

code is the stable identifier. These are every code the payment-link endpoints return.

`code`	Status	Meaning
`UNAUTHENTICATED`	`401`	No `X-API-Key` header on a route that requires one
`INVALID_API_KEY`	`401`	Unknown, revoked or deactivated key
`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
`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
`429`	`429`	Rate limited. This one carries the status as its code

A malformed request body is also a 422, raised by request validation before any of the codes above. Its message names the offending field 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 to receive payments

The key is valid and correctly scoped, but its owner cannot receive money yet: no default wallet, or no handle.This is not a transient failure and there is nothing your code can do about it. The account owner has to claim a Moove Handle and set a default wallet with a settlement token.Surface it to the user rather than retrying.

422 — validation

The request body did not match the schema. message names the field.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.

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

Coming Soon

The error body

Status codes

Error codes

The ones worth understanding

Handling errors

Next

Rate Limits

Authentication

Moove Payment Links

​The error body

​Status codes

​Error codes

​The ones worth understanding

​Handling errors

​Next

Rate Limits

Authentication

Moove Payment Links

The error body

Status codes

Error codes

The ones worth understanding

Handling errors

Next