Errors - Forward Model

Every error has the same shape: a type you can act on, a message in plain words, and the request_id.

{
  "error": {
    "type": "invalid_input",
    "message": "Name at least one symbol.",
    "request_id": "req_6f1c2a9b0d4e47a8b3c1",
    "field": "symbols"
  }
}

Some errors add a field: field for the input that was wrong, retry_after_seconds when it’s worth trying again, and resets_at when a limit resets.

Error types

Status	Type	What happened	What to do
400	`invalid_input`	A symbol can’t be a ticker, none was given, or there were more than 50. Unknown but valid-looking tickers aren’t an error; they come back under `not_scored`.	Fix the input named in `field`.
400	`invalid_date`	The date isn’t `YYYY-MM-DD`, or has no published scores (a weekend, a holiday, or today before the scores are out).	Use a recent trading day, or leave `date` out.
401	`unauthenticated`	No key, or the key isn’t recognized.	Send `Authorization: Bearer <key>`.
401	`key_revoked`	The key was deleted.	Create a new key in the console.
402	`plan_required`	Your plan doesn’t include today’s scores, or the date is older than your plan’s history.	Subscribe to Plus, or ask for a date within the last 21 trading days.
429	`limit_reached`	Your plan’s limit is reached. The whole call is refused and nothing counts.	Wait until `resets_at`; stocks you’ve seen today still come back.
429	`rate_limited`	Too many requests too quickly.	Wait `retry_after_seconds`, then retry.
503	`model_unavailable`	Scores or the plan check can’t be read right now (rare).	Retry after `retry_after_seconds`.
500	`server_error`	Something went wrong on our side.	Retry once; if it happens again, write to support with the `request_id`.

Retrying

Retry only rate_limited, model_unavailable and server_error, and wait at least as long as retry_after_seconds (also sent as the Retry-After header). Don’t retry errors in the 400s without changing the request.

Before the open

The day’s scores are published before the market opens, usually by 9:00 a.m. Eastern. Until then, and on market holidays, a call returns the latest published day; check date.

Help

Write to support@forwardmodel.ai with the request_id. It lets us find the call without you sending anything else.