Errors

Everything non-2xx the API returns, with the exact JSON shape. FastAPI validation errors (422) nest a list under detail; everything else is either a string or an object with an error slug.

400 Bad request

When: A malformed parameter — bad date format, or an invalid enum value.

{
  "detail": "Dates must be YYYY-MM-DD"
}

Fix: Check the parameter formats in the endpoint reference.

401 Missing key

When: No X-API-Key header (or ?api_key=) on the request.

{
  "detail": "API key required: X-API-Key header (get one at likefolio.ai/developers)"
}

Fix: Send your key as the X-API-Key header.

403 Invalid or inactive key

When: The key doesn't exist or was revoked. (The old daily request cap was removed 2026-07-14 — volume is limited only by credits.)

{
  "detail": "Invalid, inactive, or rate-limited API key"
}

Fix: Verify the key in your console, or mint a new one.

403 Ticker outside free coverage

When: A free key requested a ticker outside the top-100 by LikeFolio Score.

{
  "detail": {
    "error": "ticker_not_in_free_coverage"
  }
}

Fix: Upgrade for the full universe, or stick to top-100 names.

403 Higher tier required

When: The endpoint needs a higher plan (e.g. quant for events/bulk/webhooks). You are NOT charged credits for this rejection.

{
  "detail": {
    "error": "quant_tier_required",
    "upgrade": "https://likefolio.ai/developers#pricing"
  }
}

Fix: Upgrade the key's plan from your console.

404 Not found

When: No data for the requested resource (e.g. an unknown ticker).

{
  "detail": "No scores for XYZ"
}

Fix: Check the ticker; /v1/screener lists covered names.

422 Validation error

When: A numeric parameter breached its bound (e.g. limit above the max) — FastAPI validation.

{
  "detail": [
    {
      "loc": [
        "query",
        "limit"
      ],
      "msg": "Input should be less than or equal to 650",
      "type": "less_than_equal"
    }
  ]
}

Fix: Respect the documented min/max on each parameter.

429 Out of credits

When: Your monthly allowance and any prepaid credits are gone. There is no post-paid overage — you are never billed for usage you have not prepaid.

{
  "detail": {
    "error": "out_of_credits",
    "tier": "hobbyist",
    "allowance": 5000,
    "used": 5000,
    "prepaid_remaining": 0,
    "options": [
      "buy a prepaid credit pack (you choose the amount)",
      "turn on auto-topup so you never hit this",
      "upgrade at likefolio.ai/developers#pricing"
    ]
  }
}

Fix: Buy a credit pack, turn on auto-topup, or upgrade — all from your console.