Errors

Errors are JSON, never an HTML page, with the same shape for every endpoint:

{
  "error": {
    "code": "not_found",
    "message": "No listed company with the symbol ZZZZ is covered. See GET /api/v1/companies for the covered companies.",
    "docs": "https://studyingstocks.com/developers/errors#not_found"
  }
}

code is stable and meant for your code to branch on. message is for people and may change. docs links to the entry below. An invalid_parameter error can also carry a details object with a message per parameter.

unauthenticated#

HTTP 401. The X-Api-Key header is missing, or the key is malformed, unknown or revoked. See authentication.

subscription_inactive#

HTTP 403. The key is valid, but the Premium subscription behind it is not active. Renew it on your profile page.

not_found#

HTTP 404. The path does not exist, or the company is not covered: it is not listed, or we have no SEC EDGAR data for it yet.

method_not_allowed#

HTTP 405. The API is read-only: use GET.

invalid_parameter#

HTTP 422. A query parameter is invalid, for example an unknown line item, a date that is not YYYY-MM-DD or a limit above the maximum. The message names the parameter.

A query parameter that the endpoint does not document is rejected too, instead of being ignored silently: ?apikey=... or a misspelled perpage answers 422, the message lists the parameters the endpoint accepts, and details has one entry per unknown name. So a typo can never quietly return the wrong data.

rate_limited#

HTTP 429. Too many requests. Wait for the number of seconds in the Retry-After header. See rate limits.

server_error#

HTTP 500. Something went wrong on our side. The response never contains internal details. Try again later and tell us if it persists.