Errors and retries
Error contract, retries, memos and limits
Error contract
HTTP status plus a JSON body { "error": "…" } or { "message": "…" }, with a details
field for machine errors. A non-JSON body is treated as a failure. Per-endpoint codes are on
Endpoints.
| Status | Meaning | What we do |
|---|---|---|
400 | Bad input, unknown memo, or past a deadline | Never retry as is |
401 | Missing or wrong key (/api/v1/*) | Alert; never retry |
403 | Blocked address, or transaction not signed by the right wallet | Tell the user; never retry |
404 | Payment not yet on chain (openPack) | Retry shortly |
429 | Rate limited | Back off. Please send Retry-After. |
500 | Machine off, low, off balance, or empty | Hide the pack; retry later |
503 | Too many open packs | Retry shortly |
Note: at Collector Crypt a missing or wrong key on the play endpoints is not rejected; the
call just loses our memo prefix. We'd prefer a hard 401, so a typo fails loudly.
Retries
- Reads and
openPackare retried freely, so they must be safe to repeat. 429/503/WAITING_FOR_WEBHOOK: up to 3 retries, about 0.5s, 1s, 2s apart, or afterRetry-After.- We never resend a signed payment. A purchase create may be resent after a crash, so a duplicate must not charge twice. That holds because nothing moves until we sign.
Memos
- You issue a unique memo per pack; we store it and look everything up by it.
- Memos carry a prefix tied to our key, so both sides can filter our activity.
- An optional
Idempotency-Keyheader on purchase create would be welcome.
Limits
Tell us your rate limits per key and any caps on pending or unopened packs per wallet. Collector Crypt caps 50 pending and 30 unopened packs per wallet.