API errors: status codes, reveal codes and hold codes

Every refusal on this API — including a 405 and a 429 — comes back as the same JSON envelope with an HTTP status code, never as an HTML page.

{
  "error": {
    "code": "upgrade_required",
    "message": "Your reveals for this month are used up.",
    "resets_at": "2026-10-01T00:00:00.000Z",
    "reveal_code": "QUOTA_EXHAUSTED",
    "credits_needed": 1,
    "credits_remaining": 0
  }
}

error.code and error.message are always present. message is human-readable and may change. code is the stable machine token: branch on it, not on the prose.

error.code

The HTTP-level reason. These eight are the complete set, and they are enumerated in the OpenAPI document so a generated client types them as a union.

Refused writes carry a second code

error.code says which HTTP category a refusal falls into. On a refused reveal or hold, that is not enough to decide what to do next — REVEAL_REQUIRED, HELD_BY_OTHER and HOLD_COOLDOWN are three completely different next actions behind the same status. So a refused write adds a specific code, and that is the one to branch on.

reveal_code

On POST /api/v1/domains/{id}/reveal.

hold_code

On POST /api/v1/domains/{id}/hold, POST /api/v1/holds/{id}/extend and DELETE /api/v1/holds/{id}.

Extra fields

A refusal adds only the fields its code needs.

Reading a refusal

import os, requests

BASE = "https://getrevised.com/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['REVISED_API_KEY']}"}

def reveal(listing_id: str) -> dict | None:
    res = requests.post(f"{BASE}/domains/{listing_id}/reveal", headers=AUTH, timeout=30)
    if res.ok:
        return res.json()

    err = res.json()["error"]
    code = err.get("reveal_code", err["code"])

    if code == "QUOTA_EXHAUSTED":
        if err["credits_remaining"] > 0:
            print(f"{listing_id}: needs {err['credits_needed']} credits, skipping")
            return None
        raise SystemExit(f"out of credits until {err['resets_at']}")
    if code == "HELD_BY_OTHER":
        print(f"{listing_id}: held until {err['expires_at']}, skipping")
        return None
    if code == "NOT_FOUND":
        print(f"{listing_id}: gone from the directory")
        return None
    raise RuntimeError(f"{res.status_code} {code}: {err['message']}")

00aLaXEG: held until 2026-09-24T09:15:00.000Z, skipping

What is refused and what is ignored

A parameter this API documents, carrying a value it cannot honour, is a 400. The reason is that a silently dropped filter always returns more rows than you asked for — a bigger, plausible-looking page instead of an error, with no way to find out.

curl "https://getrevised.com/api/v1/domains?traffic=huge" \
  -H "Authorization: Bearer $REVISED_API_KEY"

{
  "error": {
    "code": "invalid_request",
    "message": "`traffic` must be one of: any, 100k, 1m."
  }
}

Parameters this API does not document are ignored, so analytics and cache-busting keys are safe to leave on the query string.

Two refusals worth knowing about specifically:

• An unknown category code is refused, not answered with an empty page. There is no /api/v1/categories endpoint; read codes off the category field of a page of results. See Filters.
• A cursor this endpoint did not issue is a 400 — never an empty page and never a silent resume from the middle of the feed. See Pagination.

Methods and CORS

A method an endpoint does not implement is 405 method_not_allowed with an Allow header, in this same JSON envelope. Nothing here answers an API path with an HTML page.

Cross-origin calls work. Every response carries Access-Control-Allow-Origin: *, OPTIONS answers the preflight, and the rate-limit headers are exposed to script.

Retrying

Reveals are idempotent, so a reveal whose response you lost to a network failure is safe to repeat: the repeat returns the original revealed_at and costs nothing. Taking a hold is safe to repeat too — asking for a hold you already have returns the existing one, not a second hold. Extending is not: a hold extends once, so a repeated extend after a lost response comes back ALREADY_EXTENDED. Check GET /api/v1/holds before retrying one.