api.spokenalpha.com
Error reference
Every non-2xx response returns a JSON envelope with a stable machine code, a human message, a request_id, and a documentation_url that deep-links to the matching section below.
Envelope shape
{
"error": {
"code": "data_not_yet_available",
"message": "Press-release data is not yet materialized. ...",
"request_id": "7f3a2b4d-...",
"documentation_url": "https://api.spokenalpha.com/docs/errors#data_not_yet_available"
}
}Codes
Monthly call quota for this key has been exhausted.
Each tier has a monthly call cap. Once reached, further calls are rejected until the calendar month resets at 00:00 UTC.
What to do
Upgrade your plan at /pricing, or wait for the monthly reset. Track usage in the account dashboard.
This endpoint is not included in your subscription tier.
The key is valid but the endpoint requires a higher tier than the key currently holds.
What to do
Review tier coverage in the endpoint reference and upgrade at /pricing.
Valid key, but your tier does not include this endpoint or field.
The wall between the developer API and the proprietary signal core gates certain fields and endpoints by tier.
What to do
Upgrade your plan at /pricing. The endpoint reference notes which tier each field requires.
The requested resource does not exist.
Generic not-found. More specific 404 codes (below) narrow the cause.
What to do
Verify the path and identifiers in your request.
No company in the corpus matches this ticker.
The ticker is not a US-listed symbol we cover, or is misspelled.
What to do
Confirm the symbol is a valid US-listed ticker (uppercase, e.g. AAPL).
The company exists, but we have no investor-relations page on file.
IR-page coverage is still expanding; some covered tickers lack a resolved IR URL.
What to do
Retry later as coverage grows, or contact hello@spokenalpha.com to request a specific company.
No earnings call matches this call_id.
Either the call_id is malformed/nonexistent, or its transcript comes from a source whose license forbids redistribution — both return 404, indistinguishably.
What to do
Confirm the call_id format: call_{TICKER}_{YYYY}Q{Q}_earnings. Discover valid IDs via GET /companies/{ticker}/earnings-calls.
The call exists but has not been scored yet.
Scoring runs after a call is ingested; freshly added calls may not yet have a score.
What to do
Check back after the scorer runs, or poll periodically with backoff.
The call exists but has no transcript content to summarise.
An executive summary requires transcript text, which is not available for this call.
What to do
Confirm the call has a redistributable transcript before requesting a summary.
The call has not yet been analysed.
Analysis requires a scored call. If the call is not yet scored, analysis is unavailable.
What to do
Check back after the scorer runs; analysis is generated downstream of scoring.
A request parameter or body field failed validation.
One or more inputs were missing, malformed, or out of range.
What to do
Fix the field identified in the response and consult the endpoint's parameter table.
The HTTP method is not supported on this endpoint.
For example, POSTing to a read-only GET endpoint.
What to do
Use the method documented for the endpoint in the API reference.
Per-hour rate limit or monthly quota exceeded.
Rate limits protect the service. The X-RateLimit-Reset header (epoch seconds) reports when the most-restrictive bucket refills.
What to do
Back off until X-RateLimit-Reset (or Retry-After). For sustained volume, upgrade your tier.
An unexpected error occurred on our side.
These responses include a request_id for support correlation.
What to do
Quote the request_id when contacting hello@spokenalpha.com. Safe to retry once after a brief pause.
The endpoint is scaffolded; its data has not shipped yet.
The response schema is locked so you can integrate against the contract today. The body includes a planned_launch field.
What to do
Integrate against the locked schema now; the body flips to live data on launch.
Language analysis could not be generated right now.
A transient upstream failure (timeout or model error) prevented generating the analysis.
What to do
Retry with exponential backoff. Persisting failures: contact support with the request_id.
Executive summary could not be generated right now.
A transient upstream failure prevented generating the summary.
What to do
Retry with exponential backoff. Persisting failures: contact support with the request_id.
Still stuck?
Quote the request_id from the response when you reach out — it lets us trace the exact call.