Stellar Testnet only. No real money moves. What this means

Errors and limits

Every error has the same shape and an HTTP status. Branch on error.code, not on message.

Error object

{
  "error": {
    "code": "SPLIT_MISMATCH",
    "message": "Exact shares must add up to the amount",
    "details": {
      "difference": "0.50"
    }
  }
}

details appears only on some errors: SPLIT_MISMATCH (difference), OVERPAY (youOwe, theyAreOwed), agent caps (limit, spent, window) and NEEDS_REVIEW (txHash).

Error codes

StatusCodeCauseFix
400VALIDATIONA field has the wrong type or value, the body is not a JSON object, or the Idempotency-Key is malformedRead message; fix the field
400INVALID_ADDRESSNot a valid Stellar G address (checksum included)Send a public G address
400SECRET_KEY_REJECTEDThe body contains something shaped like a secret keyNever send secret keys. Sign locally
400ASSET_NOT_SUPPORTEDAsset not configured on this serverUse USDC, or EURC when enabled
400AGENT_NOT_REGISTEREDAgent address not in AGENT_TOKENSAsk the operator to register it
400LINK_INVALIDLink message or signature bad, expired or usedRequest a new link challenge
401UNAUTHORIZEDMissing, expired or invalid token, or a failed sign-inSign in again
403FORBIDDENAn agent token on a route only people may callUse a person's session
403NOT_LINKEDAgent used onBehalfOf without an active linkLink the agent first
403AGENT_CAP_PER_PAYMENTPayment above 25Pay less, or let the owner pay
403AGENT_CAP_PER_DAYOver 50 in 24 hoursWait; details.spent shows the window
403AGENT_CAP_PER_MONTHOver 200 in 30 daysWait or let the owner pay
404NOT_FOUNDUnknown route, group, invite or link, or you are not a memberCheck the id and membership
404INTENT_NOT_FOUNDNo such intent for you as payerReserve an intent first
405METHOD_NOT_ALLOWEDPath exists, method does notCheck the method
409ALREADY_MEMBERAddress already in the groupNothing to do
409AGENT_ALREADY_LINKEDAgent has another active ownerThe other owner must revoke it
409INTENT_IN_PROGRESSPayer or creditor has another reserved intent in the groupPay or cancel it, or wait up to 10 minutes
409INTENT_NOT_OPENIntent is settled, cancelled, expired or in reviewReserve a new one
409DUPLICATE_TXTransaction hash already recordedNothing to do
409NEEDS_REVIEWPayment arrived but no longer matches an open debtKept for review with details.txHash; contact the operator
413VALIDATIONBody over 64 KB (receipt scan: over its photo limit). Connection closesSend less
422SPLIT_MISMATCHExact shares do not add upUse details.difference
422OVERPAYAmount above the debtUse details.youOwe
422NOT_A_RECEIPTPhoto is not a receiptUse another photo
422SCAN_UNREADABLEReceipt total unreadableEnter the expense by hand
429RATE_LIMITEDOver 10 receipt scans in 10 minutesWait a few minutes
500INTERNALUnexpected errorReport it on GitHub
502UPSTREAM_UNAVAILABLEHorizon or Supabase did not answerSafe to retry with backoff
503SCAN_UNAVAILABLEReceipt reader off, down or out of quotaEnter the expense by hand
503ASSET_UNAVAILABLEGroup asset no longer configured on the serverContact the operator

Settlement verification codes

When you record a settlement, the API checks the transaction on Horizon. A failed check answers 422 with one of these codes (on the x402 route, a fresh 402 with the code in error).

CodeMeaning
PAYMENT_NOT_FOUNDTransaction not found on Stellar Testnet. Wait for it to land, then retry
PAYMENT_FAILEDThe transaction failed on chain
INTENT_MISMATCHThe memo does not match the intent
TIMEBOUNDS_TOO_LONGThe transaction may land after the intent expires. Set its max time to expiresAt or earlier
PAYMENT_MISMATCHNo payment in the group asset with this payer, payee and amount
WRONG_NETWORKThe server's Horizon is not Testnet

Rate limits

The only rate limit in the code is on the receipt scan: 10 scans per person per 10 minutes, counted per serverless instance. Over it, 429 RATE_LIMITED. The API sends no rate-limit headers and no Retry-After.

async function withRetry(fn, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const res = await fn();
    if (res.status !== 429 && res.status !== 502) return res;
    await new Promise((r) => setTimeout(r, 2 ** i * 1000)); // 1s, 2s, 4s, 8s
  }
  throw new Error('gave up after retries');
}
Fair use

Other routes have no limit in the code. Vercel's platform limits still apply. Keep polling gentle.

Body limits

  • 64 KB for every body, except the receipt scan (1.4 million base64 characters of photo).
  • Over the limit: 413 with a JSON error, and the connection closes.
  • Bodies must be JSON objects. Arrays, null or invalid JSON: 400 VALIDATION.

Idempotency

POST /v1/groups/:id/expenses accepts an Idempotency-Key header (8 to 64 of A-Z a-z 0-9 - _). A repeat with the same key in the same group returns the first expense and creates nothing. Use one key per form submission. Settlements are idempotent by transaction hash: a hash is recorded once, a repeat gets 409 DUPLICATE_TX.

What is safe to retry

  • 502 UPSTREAM_UNAVAILABLE: yes, with backoff.
  • 422 PAYMENT_NOT_FOUND right after submitting: yes, after a few seconds.
  • POST .../expenses: yes, with the same Idempotency-Key.
  • A signed payment: never sign a second payment for the same intent. Record the first hash.

Versioning

All routes are under /v1. There is no other version today. Fields may be added to responses, so ignore fields you do not know.

Last updated 26 October 2026Edit this page on GitHub