DocsReferenceErrors

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 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, escrow movement or a payment route 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/trust for current ids.
404 escrow_not_found Unknown escrow id. Read /api/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 payee_required Escrow opened without a PayPal email for the provider. Add payee_paypal_email or set it on the provider profile.
422 paypal_not_configured A hold or release without PayPal credentials. Set PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET.
422 escrow_not_releasable Release on a draft, voided or already released escrow. Place the PayPal hold first, then release.
422 escrow_already_held A second hold on an authorized escrow. Read the escrow; reuse the existing authorization.
422 escrow_already_released Void or release on a released escrow. Read the escrow instead.
422 escrow_voided Release on a voided escrow. Open a new escrow.
422 proof_required Release without any receipt for the obligation. File proof for this obligation first.
422 proof_wrong_obligation Receipt belongs to a different obligation. File a receipt for this obligation.
422 proof_rejected The auditor rejected the evidence. Fix the evidence, re-audit, then release. The hold is untouched.
422 payout_failed Capture succeeded but PayPal refused the payout. Retry the payout; the escrow stays captured_awaiting_payout.
451 region_blocked Escrow movement from a blocked country. Only the operator can change BLOCKED_COUNTRIES.

Payments#

Payment routes are session-cookie routes; a machine key gets 401 unauthorized on them.

Status Code Cause Fix
404 payment_not_found Unknown order id on capture. Capture the order id from the approval redirect.
404 payout_not_found Unknown payout or batch id. Read GET /api/payments for current ids.
409 obligation_not_payable The obligation is already settled or archived. Refresh the register; pay a live obligation.
409 payout_state Paying a payout that is not processing. Request a new payout from cleared earnings.
409 paypal_email_required A seller payout without a PayPal email on the profile. Set one under Seller desk → Payout account.
422 nothing_to_pay The obligation has no amount. Set an amount above zero.
422 currency_unsupported Obligation currency is not USD. PayPal settles USD only here.
422 amount_too_large Above $10,000 per payment. Split the obligation into smaller payments.
422 amount_mismatch / currency_mismatch PayPal returned a different total than the stored row. Do not retry blindly; the payment is marked failed.
502 paypal_unreachable Network failure or timeout to PayPal. Retry; the order is idempotent on capture.
503 paypal_not_configured Missing PAYPAL_CLIENT_ID or PAYPAL_CLIENT_SECRET. Configure the rail or hide the pay control.

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 PayPal credentials.