Errors

Stable error envelope. Codes are the contract your agent should switch on — not the human message.

Envelope

{
  "error": {
    "message": "Human-readable message",
    "code": "PAYMENT_REQUIRED",
    "type": "validation_error",
    "details": []
  }
}

Key codes

Code	Typical HTTP	Retry?
VALIDATION_ERROR	400	No
PAYMENT_REQUIRED	402	After pay
X402_INVALID_PAYMENT	402	No
X402_SETTLEMENT_FAILED	402	Maybe
MPP_CHALLENGE_EXPIRED	402	Yes
MPP_INVALID_CREDENTIAL	402	No
MPP_SETTLEMENT_FAILED	402	Maybe
PREPAID_INSUFFICIENT	402	After top-up
NOT_VERIFIED	403	No
CONSOLE_LINK_INVALID	401	No
CONSOLE_LINK_EXPIRED	401	No
CONSOLE_CHALLENGE_RATE_LIMITED	429	Yes
CONSOLE_PHONE_NOT_FOUND	404	No
RATE_LIMITED	429	Yes
CONVERSATION_STREAK_LIMIT	429	No
OUTBOUND_LIMIT_REACHED	429	No
CARRIER_REJECTED	422	No
CARRIER_UNAVAILABLE	503	No
IGNORED_RECIPIENT	422	No
TCPA_QUIET_HOURS	422	Later
CELL_NOT_READY	409	Yes
PHONE_NOT_ASSOCIATED	409	No
FLEET_REQUIRED	403	After pay
MMS_NOT_SUPPORTED	400	No
RESTART_NOT_SUPPORTED	501	No
FACILITATOR_UNAVAILABLE	503	No
CYCLE_JOB_NOT_FOUND	404	No
PHONE_KEY_EXPIRED	401	No
INVALID_CONFIRMATION	400	No
PROVISION_FAILED	500	Maybe

Copy for Cursor / Claude

VALIDATION_ERROR — Fix the request body.
PAYMENT_REQUIRED — Settle Stripe, x402, or MPP.
X402_INVALID_PAYMENT — Signature did not verify.
X402_SETTLEMENT_FAILED — Retry settlement.
MPP_CHALLENGE_EXPIRED — Request a new challenge.
MPP_INVALID_CREDENTIAL — Credential rejected.
MPP_SETTLEMENT_FAILED — Retry MPP settlement.
PREPAID_INSUFFICIENT — Prepaid balance too low.
NOT_VERIFIED — Complete agent verify.
CONSOLE_LINK_INVALID — Create a new login link.
CONSOLE_LINK_EXPIRED — Create a new login link.
CONSOLE_CHALLENGE_RATE_LIMITED — Slow OTP requests.
CONSOLE_PHONE_NOT_FOUND — Must be sign-up human_phone.
RATE_LIMITED — Honor Retry-After.
CONVERSATION_STREAK_LIMIT — Wait for a reply.
OUTBOUND_LIMIT_REACHED — Daily cap.
CARRIER_REJECTED — Carrier refused the message.
CARRIER_UNAVAILABLE — No carrier configured; production send is fail-closed.
IGNORED_RECIPIENT — Number is ignored.
TCPA_QUIET_HOURS — Outside pod quiet hours.
CELL_NOT_READY — Cell has no E.164 yet; poll health.
PHONE_NOT_ASSOCIATED — No phone on this workspace or pod.
FLEET_REQUIRED — New accounts cannot read usage/analytics until purchase or a cell exists.
MMS_NOT_SUPPORTED — SMS only; MMS is later.
RESTART_NOT_SUPPORTED — Remote restart/ADB is later, like MMS.
FACILITATOR_UNAVAILABLE — x402 facilitator not configured.
CYCLE_JOB_NOT_FOUND — Unknown cycle job.
PHONE_KEY_EXPIRED — Device API key expired.
INVALID_CONFIRMATION — Provisioning confirm failed.
PROVISION_FAILED — Device provisioning failed.