Docs / Server verify / Ruby

Verify Playtcha from Ruby

This page is the server-side contract for Ruby apps. Your backend receives the client-submitted result token, posts it to /v1/verify with your secret key, and only then decides whether to continue the request.

Minimal example

The minimal shape is still { secret, token } over JSON, then block the request unless success is true.

verify_playtcha.rb

require "json"
require "net/http"
require "uri"

def verify_playtcha(token)
  return {
    "success" => false,
    "error" => { "code" => "missing_token", "message" => "Missing result token" },
  } if token.to_s.empty?

  uri = URI("https://playtcha.com/v1/verify")
  res = Net::HTTP.post(
    uri,
    { secret: ENV.fetch("PLAYTCHA_SECRET"), token: token }.to_json,
    "Content-Type" => "application/json",
  )

  JSON.parse(res.body)
rescue StandardError
  {
    "success" => false,
    "error" => { "code" => "network_error", "message" => "Couldn't reach Playtcha verify" },
  }
end

Production-ready example

In production, add timeouts, log the upstream error envelope, and treat degraded mode as quota state rather than a failed verification.

verify_playtcha_prod.rb

require "json"
require "net/http"
require "uri"

# Implements the fail-open contract.
#   5xx / network    -> log + treat as verified (unless PLAYTCHA_FAIL_CLOSED=1)
#   4xx              -> reject deterministically
#   429              -> reject + honor Retry-After (don't tighten retries)
#
# The 'ok' / 'unavailable' keys are LOCAL to this helper. Playtcha's wire
# format has no success:false field on errors; the envelope is { error: {...} }.
def verify_playtcha(token)
  if token.to_s.empty?
    return { ok: false, status: 0, unavailable: false,
             error: { "code" => "missing_token", "message" => "Missing result token" } }
  end

  uri = URI("https://playtcha.com/v1/verify")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  http.read_timeout = 5
  http.open_timeout = 5

  req = Net::HTTP::Post.new(uri.request_uri, { "Content-Type" => "application/json" })
  req.body = { secret: ENV.fetch("PLAYTCHA_SECRET"), token: token }.to_json

  res = http.request(req)
  data = JSON.parse(res.body) rescue {}
  status = res.code.to_i

  if status >= 500
    { ok: false, status: status, unavailable: true,
      error: { "code" => "verifier_unavailable", "message" => "5xx" } }
  elsif status >= 400
    # 4xx upstream error envelope: { error: { code, message, request_id, hint?, host? } }
    { ok: false, status: status, unavailable: false,
      error: data["error"] || { "code" => "unknown_error", "message" => "" } }
  else
    { ok: true, data: data }
  end
rescue StandardError => e
  { ok: false, status: 0, unavailable: true,
    error: { "code" => "network_error", "message" => e.message } }
end

# Sinatra / Rails-style usage
fail_closed = ENV["PLAYTCHA_FAIL_CLOSED"] == "1"
result = verify_playtcha(params["playtcha-token"])

if !result[:ok]
  if result[:unavailable]
    logger.warn("playtcha.verify.unavailable status=#{result[:status]}")
    halt 503, { error: "verifier_unavailable" }.to_json if fail_closed
    # fall through — treat as verified
  else
    # 409 already_redeemed is a security signal: replay, stuck retry, or duplicate POST.
    # Log with request_id at warn level — do not silently retry.
    logger.warn(
      "playtcha.verify.failed status=#{result[:status]} " \
      "code=#{result[:error]['code']} request_id=#{result[:error]['request_id']}"
    )
    halt 400, { error: "verification-failed" }.to_json
  end
elsif result[:data]["degraded"]
  logger.info("playtcha.verify.degraded reason=#{result[:data]['degraded_reason']}")
end

Common gotchas

Set read and open timeouts so verify stays bounded inside signup or form-submit flows.
Fail open on 5xx and network errors; fail closed on 4xx. Opt into PLAYTCHA_FAIL_CLOSED=1 for high-fraud paths.
On non-2xx responses, inspect the upstream error envelope ({ error: { code, message, request_id, ... } }) instead of assuming a success-shaped payload.
The wire format has no success: false field on errors. Any success-style key in helper code is a local discriminator.
Treat degraded=true as success and keep it in logs or metrics, not in user-facing failure copy.
409 already_redeemed is single-use-by-design. In production it means replay, stuck retry, or duplicate POST. Log with request_id at warn level — do not retry.
429 rate_limited_ip means per-IP throttle. Honor the Retry-After header; do not retry tighter than 1s.

Relevant failure codes

Status	Code	Meaning
401	`token_invalid`	Bad signature or claims. Often wrong env (live vs test).
401	`bad_secret`	Secret does not match the project. Config error.
404	`unknown_project`	Project deleted or never existed.
409	`already_redeemed`	Security signal. Single-use by design. Log with `request_id` at warn level.
410	`token_expired`	Result token TTL elapsed (5 minutes).
429	`rate_limited_ip`	Per-IP throttle. Response has `Retry-After` header.
500	`db_error`	Playtcha-side. Fail open.

Where to go next

Pair this with token lifecycle for the token model, or domain whitelist if your issue happens before verify on the public widget endpoints.