Errors
An error from an endpoint includes a machine-readable code, a human-readable error message, and a link back to this page so you can look up exactly what went wrong.
Error format#
Errors return JSON with the standard fields below. A field that does not apply is left out: param appears only when one parameter is to blame.
{
"error": "Missing required parameter: exchange",
"code": "missing_parameter",
"param": "exchange",
"documentation_url": "https://earningscall.biz/docs/errors#missing_parameter",
"request_id": "1edc01c0-e099-4191-8b27-5e30ebd7a72e"
}request_id identifies this one request. The same value is in the x-request-id response header. Quote it when you contact support and we can find the request on our side.
The documentation_url field always points at this page — the anchor matches the error code, so the link drops you right at the explanation.
code field, not the human-readable error message — the message is intended for humans and may change.One response is not JSON. A request to a path the API does not have, such as /v9/events, gets a 404 in plain text: Endpoint GET /v9/events not found. Check the content-type before you parse an error body.
All error codes#
missing_parameter — Missing parameter400#
A required query parameter is missing. The error response includes a param field naming the missing parameter.
How to fix: Check the endpoint reference for the full list of required parameters and re-send the request with the missing one supplied.
invalid_parameter — Invalid parameter400#
A parameter is the wrong type or out of range — for example a non-integer where a year is expected, or a quarter outside 1–4.
How to fix: Verify the value matches the type and range documented for that parameter.
missing_api_key — Missing API key401#
No API key was supplied. The API expects a key on every request, either as the apikey query parameter or the x-api-key header.
How to fix: Send your API key on the request. See the Authentication guide for how.
invalid_api_key — Invalid API key401#
The API key sent does not match an active key on file.
How to fix: Confirm you copied the key correctly from your account dashboard. If the key was rotated or deleted, generate a new one.
demo_restriction — Demo restriction403#
The demo API key was used to request data outside the demo allowlist. Demo keys can only access tickers NASDAQ:AAPL and NASDAQ:MSFT, and only 2025-01-10 on the calendar endpoint.
How to fix: Either request demo-allowed data, or upgrade to a paid plan for full access.
plan_restriction — Plan restriction403#
Your plan does not include the requested feature — for example a Basic plan requesting transcript level 2, or a non-Enterprise plan requesting slide PDFs or transcript search.
How to fix: Upgrade your plan from the pricing page to unlock the feature.
resource_not_found — Resource not found404#
The exact resource you asked for does not exist — for example a transcript for a year/quarter we have not yet processed.
How to fix: List available events with GET /events to confirm what's on file before requesting a transcript or audio file.
rate_limit_exceeded — Rate limit exceeded429#
You've sent more requests than your plan allows. The response includes a retry-after header indicating how many seconds to wait.
How to fix: Slow your request rate, batch where possible, or upgrade to a higher-tier plan.
trial_quota_exceeded — Trial quota exceeded403#
A free-trial key has used all of its calls. A trial has a fixed number of calls for its whole life, so waiting does not bring them back — which is why this is a 403 and not a 429. Every response to a trial key carries x-trial-calls-remaining, so you can see it coming.
How to fix: Choose a plan on the pricing page to keep going.
service_unavailable — Service unavailable503#
A backing service (search index, live-events cache) is temporarily unavailable. The API includes a Retry-After header — usually a small number of seconds.
How to fix: Retry with backoff. If it keeps failing, contact support with the request_id.
internal_error — Internal error500#
Something unexpected went wrong on our end. We monitor and alert on these — you don't need to file a ticket unless they persist.
How to fix: Retry once. If it keeps failing on the same request, contact support with the request_id.
Related#
- Rate limiting — details on 429 responses and the headers we return.
- Plans — feature matrix that determines when you'll see
plan_restriction. - Authentication — how to send your API key.