Error reference

All errors return a JSON body with an error field and usually a message.

HTTP	error	When
400	missing_field / invalid_inbox	Missing or invalid request body (e.g. inbox required)
401	unauthorized	Missing or malformed API key
401	key_revoked	API key has been revoked
403	forbidden	Inbox not registered to this account
403	plan_restriction	Feature not in current plan (OTP, WebSocket, custom domain)
403	domain_not_verified	Custom domain not verified in dashboard
404	not_found	Message or inbox not found
409	already_registered	Inbox already registered to this account
429	rate_limit_exceeded	Per-second limit hit (Retry-After header)
429	monthly_quota_exceeded	Monthly quota exhausted, no credits
500	server_error	Internal server error

All errors include success: false and an error code. Example:

403Plan restriction (example)

json

{
  "success": false,
  "error": "plan_restriction",
  "message": "OTP extraction requires Developer plan or higher. Your current plan: free.",
  "upgrade_url": "https://freecustom.email/api/pricing"
}