Errors

Errors in this API are named, enumerable and mostly not HTTP errors. Two properties matter more than any individual code, and getting them wrong is the usual cause of a brittle client.

Two rules before the table

1. Branch on reason, not only on status

A great many refusals are returned with HTTP 200. That is deliberate: the request was well-formed, it was understood, and the answer is a fact about your account or the catalogue rather than a protocol failure. “Every product is spoken for right now” is not a 4xx. The same reason code can also carry different HTTP statuses on different endpoints, so reason is the stable key.

{
  "status": "refused",
  "reason": "claimed_by_another_founder",
  "explanation": "Another founder claimed this one first. Your other candidates are still yours to take."
}

status is one of refused, error, abstained, or a domain state such as ok, proposed, not_claimed, quiet, attention. Some routes on the proof surface use the shape {"error":"not_found","reason":…} instead; handle both.

2. The vocabulary is served, so generate against it

GET /api/reasons returns the complete registry — every code the server can emit, with its sentence — and it is asserted in both directions: a code the server can emit but has not declared fails the build, and a code declared but unreachable fails it too. So a client can be generated from the live registry rather than from a list a human transcribed.

curl -s https://flowfinds.ai/api/reasons | python3 -c '
import json, sys
d = json.load(sys.stdin)
print(d["count"], "reason codes")
for code, sentence in sorted(d["reasons"].items()):
    print(f"{code:38} {sentence}")'

The table below is written from that registry, grouped by the surface that raises each code. Where a code is emitted by more than one endpoint with a different HTTP status, both statuses are given.

Every reason code

HTTP statuses, and what each one means here

A handler that ages well

TERMINAL = {
    "claimed_by_another_founder", "passed_by_you", "not_shown",
    "catalog_exhausted", "passed_out", "legacy_checkout_retired",
}

def handle(response, reasons):
    body = response.json()
    reason = body.get("reason")
    if body.get("status") not in ("refused", "error") and "error" not in body:
        return body                                  # a real answer, or a domain state

    # The registry is the source of truth for the sentence. Never invent copy for a
    # code you do not recognise — print what the server says it means.
    sentence = reasons.get(reason, body.get("explanation", "refused"))

    if reason in TERMINAL:
        raise Terminal(reason, sentence)
    if response.status_code == 429:
        raise Throttled(reason, sentence, resets_at=body["resets_at"])
    if reason == "internal":
        raise ServerFault(sentence)
    raise Refused(reason, sentence)

reasons = requests.get(f"{BASE}/api/reasons").json()["reasons"]

The important line is the fallback. A code your build has never seen still has a correct sentence, because the sentence came from the same server that raised it.

Next: Troubleshooting · Rate limits and quotas · API reference