sifting/io
Operations · REST

Errors & rate limits.

Every error code the SiftingIO REST API can return, the envelope shape, and the rate-limit headers every response carries.

Error envelope

Every error response carries a JSON body with an error code and a human-readable message. HTTP status follows standard conventions; the error code (snake_case) is the stable machine-readable identifier you should switch on.

error envelope · application/json
{ "error": "error_code", "message": "human-readable details" }

Error codes

Switch on the snake_case error field. HTTP status maps loosely to category, the code is what stays stable.

  • 400(raw message)

    Malformed query, invalid cursor, bad limit, missing required parameter.

  • 401unauthorized

    API key missing or invalid.

  • 403(raw message)

    Authenticated but not entitled, your subscription doesn't include this product or market.

  • 404unknown_ticker

    :ticker not in the SEC's US ticker registry.

  • 404unknown_filer

    :filer (ticker or CIK) not found.

  • 404filing_not_found

    Specific accession isn't in this filer's recent-filings window.

  • 404no_13f_filings

    Filer has never filed 13F-HR.

  • 404not_found

    Concept / period / unit combination has no data, or symbol absent from live feed.

  • 404section_not_found

    Requested filing section couldn't be extracted, body includes `available` (sections that were extracted).

  • 404insufficient_filings

    Risk-factors diff needs ≥ 2 10-Ks; this filer has fewer on record.

  • 400invalid_section

    :section not in the allowed list, body includes `valid_options`.

  • 400invalid_accession_format

    Accession number didn't match the dashed/undashed shape.

  • 400invalid_date_range

    Economic calendar: `to` must be strictly after `from`, range capped at 365 days.

  • 406gzip_required

    Heavy endpoint called without Accept-Encoding: gzip.

  • 422risk_factors_unavailable

    Item 1A couldn't be extracted from one or both 10-K filings being diffed.

  • 429rate_limit_exceeded

    Per-tier rate budget exhausted, inspect Retry-After.

  • 502upstream_error

    Filings source returned a non-success status. Retry shortly.

  • 502malformed_upstream

    Filings source returned an invalid payload, or live snapshot couldn't be parsed.

  • 503stale_snapshot

    Live snapshot older than the configured threshold (default 5s). Body carries last_t and server_now.

  • 503upstream_rate_limited

    Filings source throttled our pipeline. Retry shortly.

Rate-limit headers

Every REST response carries these. Read them to self-throttle before you hit a 429.

  • X-RateLimit-Limit

    Token bucket burst capacity for your subscription tier.

  • X-RateLimit-Remaining

    Tokens remaining in the current window.

  • Retry-After

    Seconds to wait before retrying. Sent on 429 responses.

Plan budgets

Per-tier budgets live on the pricing page. Upgrades raise the per-minute and per-day buckets without changing the headers or codes.

See pricing tiersQuickstart