Reference

Errors & retries

HTTP status meanings for Partner Transfer, common Pro/Ledger failures, and how to retry safely.

Partner Transfer API

Base: https://araojncyittkahvvpdrn.supabase.co/functions/v1/partner-transfer-api

Status	Meaning	Action
401	Missing / invalid / revoked key	Rotate key in partner portal; never ship keys to clients
403	Origin not whitelisted	Allowlist exact redirect / Origin in partner app settings
404	Recipient or charge not found	Resolve /accounts/:id first; verify charge id
400	Validation / insufficient balance	Fix amount, currency, or fund hot wallet — do not blind-retry
409	Idempotency conflict (if returned)	Reuse same Idempotency-Key; treat as success if body matches
429 / 5xx	Rate limit or upstream	Exponential backoff; keep Idempotency-Key on transfers

# Safe transfer retry pattern
curl -X POST "https://araojncyittkahvvpdrn.supabase.co/functions/v1/partner-transfer-api/transfers" \
  -H "Authorization: Bearer opk_live_YOUR_KEY" \
  -H "Idempotency-Key: order_1234_transfer" \
  -H "Content-Type: application/json" \
  -d '{"to":"@alice","amount":10.00,"note":"Payout"}'

Charges (no webhooks)

Statuses: created, paid, canceled, expired (2h TTL).
After checkout return, poll GET /charges/:id until terminal — do not assume success from redirect alone.
Cancel only while created: POST /charges/:id/cancel.

Public Ledger API

4xx — bad cursor / asset filter; fix query.
5xx / empty — retry with backoff; page is append-only so duplicates are safe to ignore by id.
Full guide: /docs/ledger

MCP / Agent Connect

Not authenticated — complete OAuth; retry tool.
Tool handler errors return isError: true with a text message — surface to the user; do not invent balances.
See /docs/mcp#errors

Pro app / migrations

UI toasts that mention missing tables (e.g. asset_chat_messages, global_chat_messages) mean a Supabase migration was not applied — run the matching file under supabase/migrations. These are not Partner API errors.