Error reference#
Errors are JSON:
json
{ "error": "code", "message": "A sentence a human can act on." }
Some add fields such as scope, plan, limit or retry_after. The HTTP status is the first signal; the error code is the contract.
Authentication and accounts#
| Status |
Code |
Cause |
Fix |
401 |
unauthorized |
No session cookie or a machine key on an app route. |
Sign in, or use /api/v1/* with a bearer key. |
401 |
invalid_credentials |
Wrong email or password. |
Retry; reset the password if needed. |
401 |
challenge_expired |
Wallet challenge missing, consumed or older than ten minutes. |
Request a new challenge. |
401 |
invalid_signature |
Wallet signature did not verify. |
Sign the exact challenge message with the same address. |
401 |
key_expired |
Machine key past expires_at. |
Rotate the key and deploy the new secret. |
403 |
missing_scope |
Key lacks the scope for this endpoint. |
Issue a key with the scope, or use a different key. |
403 |
email_unverified |
A paid plan change needs a confirmed address. |
Confirm the email, then retry. |
409 |
email_taken |
Signup for an existing address. |
Sign in instead. |
422 |
invalid_email |
Malformed address or longer than 254 characters. |
Send a valid address. |
422 |
weak_password |
Password outside 8–256 characters. |
Use a longer password. |
429 |
rate_limited |
Too many auth attempts. |
Wait for Retry-After or a minute. |
451 |
region_blocked |
New account or escrow movement from a blocked country. |
Only the operator can change BLOCKED_COUNTRIES. |
Machine API#
| Status |
Code |
Cause |
Fix |
401 |
unauthorized |
Missing, malformed or unknown bearer key. |
Check Authorization: Bearer rfy_live_.... |
403 |
missing_scope |
The key does not include the needed scope. |
Issue a scoped key. |
404 |
not_found |
Unknown path or obligation. |
Check the id and path. |
409 |
idempotency_conflict |
Same Idempotency-Key, different body, within 24 hours. |
Use a new key for a different operation. |
422 |
title_required |
Creating an obligation without a title. |
Send title. |
422 |
obligation_id_required |
Filing a receipt without obligation_id. |
Send the id. |
429 |
rate_limited |
Per-key request window exceeded. |
Back off using Retry-After. |
429 |
plan_limit |
Monthly machine calls exhausted. |
Upgrade the plan or wait for the next month. |
402 |
plan_limit |
Agent key allowance exhausted. |
Remove a key or upgrade. |
500 |
server_error |
Unhandled server failure. |
Retry if idempotent; report with the path and response. |
Trust and escrow#
| Status |
Code |
Cause |
Fix |
404 |
receipt_not_found |
Unknown receipt id. |
Read /api/v1/trust for current ids. |
422 |
obligation_not_found |
Escrow or receipt references an unknown obligation. |
Check the id in the same workspace. |
422 |
amount_required |
Escrow amount is zero or not a number. |
Send a positive amount. |
422 |
jurisdiction_ack_required |
Escrow created without the acknowledgement. |
Send "jurisdiction_ack": true after reading the boundary. |
422 |
escrow_contract_not_configured |
Onchain funding without an escrow contract. |
Use /commit for an offchain intent, or configure the contract. |
422 |
escrow_contract_changed |
Contract changed after the intent was opened. |
Open a new escrow. |
422 |
receipt_lookup_failed |
RPC could not read the transaction. |
Check the hash, chain and RPC. |
422 |
transaction_not_found |
No transaction for that hash. |
Wait for confirmation and retry. |
422 |
transaction_reverted |
The funding transaction failed. |
Send a successful transaction. |
422 |
wrong_contract |
Transaction did not target the escrow contract. |
Fund the contract recorded on the escrow. |
422 |
proof_required |
Release without a signed or anchored receipt. |
Sign a receipt for the obligation first. |
422 |
proof_wrong_obligation |
Receipt belongs to a different obligation. |
File and sign a receipt for this obligation. |
422 |
proof_not_signed |
Receipt is still prepared. |
Sign or anchor it. |
422 |
signature_invalid |
Recovered address does not match signer. |
Sign the exact typed data with that address. |
422 |
escrow_not_draft |
Commit on an already committed escrow. |
Open a new intent. |
422 |
escrow_not_releasable |
Release on a draft or released escrow. |
Commit or fund it first. |
422 |
escrow_already_funded / escrow_already_released |
Duplicate state transition. |
Read the escrow instead. |
Connection and execution#
| Symptom |
Cause |
Fix |
| Connector never runs |
No executor connected, or the obligation is below approve. |
Connect an executor in the passport; raise autonomy. |
connector_<status> proof |
The executor returned 2xx without a proof reference. |
Return {"proof": "..."}. |
Run failed, no retry |
The executor returned a non-transient 4xx. |
Fix the request contract; the server treats it as final. |
| Repeated retries |
408, 429, 5xx, timeout or network failure. |
Fix availability; the outbox retries with backoff. |
executor_url_invalid |
Not HTTPS, local address without opt-in, or a redirect. |
Use a public HTTPS endpoint; EXECUTOR_ALLOW_LOCAL=1 locally. |
| Duplicate side effects |
At-least-once delivery. |
Dedupe on x-remindify-run. |
Job stuck pending |
Scheduler not running on serverless. |
Call /api/cron/outbox with the secret. |
Cron routes#
| Status |
Code |
Cause |
Fix |
404 |
not_found |
No secret configured, so the route is hidden. |
Set OUTBOX_SECRET or CRON_SECRET. |
401 |
unauthorized |
Missing or wrong bearer secret. |
Send the exact secret. |
Reporting a problem#
Include:
- the time and timezone,
- the method and path,
- the HTTP status and full JSON body,
- the key prefix (the first 13 characters), never the secret,
- the run id for connector issues.
Do not include the signing secret, session cookie, machine key or wallet seed phrase.