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
| Status | Code | Cause | Fix |
|---|---|---|---|
400 | VALIDATION | A field has the wrong type or value, the body is not a JSON object, or the Idempotency-Key is malformed | Read message; fix the field |
400 | INVALID_ADDRESS | Not a valid Stellar G address (checksum included) | Send a public G address |
400 | SECRET_KEY_REJECTED | The body contains something shaped like a secret key | Never send secret keys. Sign locally |
400 | ASSET_NOT_SUPPORTED | Asset not configured on this server | Use USDC, or EURC when enabled |
400 | AGENT_NOT_REGISTERED | Agent address not in AGENT_TOKENS | Ask the operator to register it |
400 | LINK_INVALID | Link message or signature bad, expired or used | Request a new link challenge |
401 | UNAUTHORIZED | Missing, expired or invalid token, or a failed sign-in | Sign in again |
403 | FORBIDDEN | An agent token on a route only people may call | Use a person's session |
403 | NOT_LINKED | Agent used onBehalfOf without an active link | Link the agent first |
403 | AGENT_CAP_PER_PAYMENT | Payment above 25 | Pay less, or let the owner pay |
403 | AGENT_CAP_PER_DAY | Over 50 in 24 hours | Wait; details.spent shows the window |
403 | AGENT_CAP_PER_MONTH | Over 200 in 30 days | Wait or let the owner pay |
404 | NOT_FOUND | Unknown route, group, invite or link, or you are not a member | Check the id and membership |
404 | INTENT_NOT_FOUND | No such intent for you as payer | Reserve an intent first |
405 | METHOD_NOT_ALLOWED | Path exists, method does not | Check the method |
409 | ALREADY_MEMBER | Address already in the group | Nothing to do |
409 | AGENT_ALREADY_LINKED | Agent has another active owner | The other owner must revoke it |
409 | INTENT_IN_PROGRESS | Payer or creditor has another reserved intent in the group | Pay or cancel it, or wait up to 10 minutes |
409 | INTENT_NOT_OPEN | Intent is settled, cancelled, expired or in review | Reserve a new one |
409 | DUPLICATE_TX | Transaction hash already recorded | Nothing to do |
409 | NEEDS_REVIEW | Payment arrived but no longer matches an open debt | Kept for review with details.txHash; contact the operator |
413 | VALIDATION | Body over 64 KB (receipt scan: over its photo limit). Connection closes | Send less |
422 | SPLIT_MISMATCH | Exact shares do not add up | Use details.difference |
422 | OVERPAY | Amount above the debt | Use details.youOwe |
422 | NOT_A_RECEIPT | Photo is not a receipt | Use another photo |
422 | SCAN_UNREADABLE | Receipt total unreadable | Enter the expense by hand |
429 | RATE_LIMITED | Over 10 receipt scans in 10 minutes | Wait a few minutes |
500 | INTERNAL | Unexpected error | Report it on GitHub |
502 | UPSTREAM_UNAVAILABLE | Horizon or Supabase did not answer | Safe to retry with backoff |
503 | SCAN_UNAVAILABLE | Receipt reader off, down or out of quota | Enter the expense by hand |
503 | ASSET_UNAVAILABLE | Group asset no longer configured on the server | Contact 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).
| Code | Meaning |
|---|---|
PAYMENT_NOT_FOUND | Transaction not found on Stellar Testnet. Wait for it to land, then retry |
PAYMENT_FAILED | The transaction failed on chain |
INTENT_MISMATCH | The memo does not match the intent |
TIMEBOUNDS_TOO_LONG | The transaction may land after the intent expires. Set its max time to expiresAt or earlier |
PAYMENT_MISMATCH | No payment in the group asset with this payer, payee and amount |
WRONG_NETWORK | The 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');
}import time
def with_retry(call, tries=4):
for i in range(tries):
res = call()
if res.status_code not in (429, 502):
return res
time.sleep(2 ** i)
raise RuntimeError("gave up after retries")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:
413with a JSON error, and the connection closes. - Bodies must be JSON objects. Arrays,
nullor 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_FOUNDright after submitting: yes, after a few seconds.POST .../expenses: yes, with the sameIdempotency-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.