Docs / Server verify / Python

Verify Playtcha from Python

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

Minimal example

The shortest correct shape is still { secret, token } plus a timeout.

verify_playtcha.py

import json
import os
from urllib import request as urllib_request, error

VERIFY_URL = "https://playtcha.com/v1/verify"

def verify_playtcha(token: str):
    if not token:
        return {
            "success": False,
            "error": {"code": "missing_token", "message": "Missing result token"},
        }

    body = json.dumps({
        "secret": os.environ["PLAYTCHA_SECRET"],
        "token": token,
    }).encode("utf-8")

    req = urllib_request.Request(
        VERIFY_URL,
        data=body,
        headers={"Content-Type": "application/json"},
        method="POST",
    )

    try:
        with urllib_request.urlopen(req, timeout=5) as res:
            return json.loads(res.read().decode("utf-8"))
    except error.URLError:
        return {
            "success": False,
            "error": {
                "code": "network_error",
                "message": "Couldn't reach Playtcha verify",
            },
        }

Production-ready example

In production, preserve the upstream error envelope in logs and remember that degraded still means success.

verify_playtcha_prod.py

# Python 3.10+. 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)
import json
import logging
import os
from urllib import request as urllib_request, error

log = logging.getLogger(__name__)
VERIFY_URL = "https://playtcha.com/v1/verify"
FAIL_CLOSED = os.environ.get("PLAYTCHA_FAIL_CLOSED") == "1"


def verify_playtcha(token: str) -> dict:
    """
    Returns a helper-shaped result. The 'ok' key is local — Playtcha's wire
    format has no success:false field on errors, only an { error: {...} } envelope.

    {"ok": True, "data": {success, degraded, ...}}                                 -> verified
    {"ok": False, "status": 4xx, "error": {code, message, request_id, ...},
                  "unavailable": False}                                            -> 4xx, reject
    {"ok": False, "status": 5xx_or_0, "error": {...}, "unavailable": True}         -> 5xx/network, fail open
    """
    if not token:
        return {"ok": False, "status": 0, "error": {"code": "missing_token", "message": "Missing result token"}, "unavailable": False}

    payload = json.dumps({"secret": os.environ["PLAYTCHA_SECRET"], "token": token}).encode("utf-8")
    req = urllib_request.Request(
        VERIFY_URL,
        data=payload,
        headers={"Content-Type": "application/json"},
        method="POST",
    )

    try:
        with urllib_request.urlopen(req, timeout=5) as res:
            data = json.loads(res.read().decode("utf-8"))
            return {"ok": True, "data": data}
    except error.HTTPError as exc:
        try:
            data = json.loads(exc.read().decode("utf-8"))
        except Exception:
            data = {}
        if exc.code >= 500:
            return {"ok": False, "status": exc.code, "error": {"code": "verifier_unavailable", "message": "5xx"}, "unavailable": True}
        # 4xx — upstream error envelope: { error: { code, message, request_id, hint?, host? } }
        return {"ok": False, "status": exc.code, "error": data.get("error", {"code": "unknown_error", "message": ""}), "unavailable": False}
    except error.URLError:
        return {"ok": False, "status": 0, "error": {"code": "network_error", "message": "Couldn't reach Playtcha verify"}, "unavailable": True}


# Flask example
@app.post("/submit")
def submit():
    result = verify_playtcha(request.form.get("playtcha-token", ""))

    if not result["ok"]:
        if result["unavailable"]:
            log.warning("playtcha.verify.unavailable status=%s", result["status"])
            if FAIL_CLOSED:
                return {"error": "verifier_unavailable"}, 503
            # fall through — treat as verified
        else:
            # 409 already_redeemed is a security signal: replay, stuck retry, or duplicate POST.
            # Log it with request_id at warn level — do not silently retry.
            log.warning(
                "playtcha.verify.failed status=%s code=%s request_id=%s",
                result["status"],
                result["error"].get("code"),
                result["error"].get("request_id"),
            )
            return {"error": "verification-failed"}, 400
    else:
        if result["data"].get("degraded"):
            log.info("playtcha.verify.degraded reason=%s", result["data"].get("degraded_reason"))

    return {"ok": True}

Common gotchas

Do not verify from browser-side Python wrappers or edge client code that would expose the secret key.
Fail open on 5xx and network errors; fail closed on 4xx. Opt into PLAYTCHA_FAIL_CLOSED=1 for high-fraud paths.
Treat degraded=True as success. It is a usage-band signal, not a failed human check.
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.
The wire format has no success:false field on errors. The envelope is { error: { code, message, request_id, ... } }.
On non-2xx verify responses, parse the upstream error envelope instead of assuming an error_codes array.
Use a timeout so verify stays a bounded dependency in signup or contact-form flows.

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 you are debugging origin failures before verify ever runs.