Enums and Errors

Every enum value and every error code on /v2/* and /x402/v2/*, in one place. Auto has its own: see Auto.

Enums

Chat

Field	Values	Meaning
analysisType	chat, macro, summary, tokenIntro, tokenAnalysis, accountAnalysis	What kind of answer to produce. Default chat. Each needs different inputs: see Analysis Types
speed	fast, expert, adaptive	Response quality mode. Default expert. adaptive is not available on x402
data.sources[].kind	x_post, x_account, telegram, dex, explorer, prediction_market, web	What a source link points at: a post on X, an X profile, a Telegram channel or message, a DEX pair or token page, a block-explorer page, a Polymarket or Kalshi market, or any other page. A string, not a closed enum: treat a value you do not recognise as web

POST /v2/chat/stream sends events whose data: payload is one of these types:

Event	Meaning
session_info	sessionId and analysisType
title	A generated session or analysis title
text	Incremental Markdown content
text_complete	Incremental text has finished
status	A progress update
credits	Credits consumed
complete	Final sessionId, success and creditsConsumed, plus sources when the request set includeSources: true
invalid_request	Safety checks rejected the query
error	The stream failed

The stream ends with data: [DONE]. A : keep-alive comment may arrive during long gaps. See Chat Stream.

Mentions

Field	Values	Meaning
data[].type	post, repost, quote, reply, note, article	The kind of X post. Returned by top mentions, keyword mentions and token news
searchType (parameter)	and, or	and: every keyword must match. or: any keyword matches. On keyword mentions and event summary. Event summary defaults to or on /v2 and and on /x402/v2

Trending

Field	Values	Meaning
chain	ethereum, solana	The chain of a trending contract address, on X and Telegram

Narratives

Field	Values	Meaning
timeFrame (parameter)	day, week	The period trending narratives analyses. Default day

Key Status

Field	Values	Meaning
status	active, revoked, expired, payment_required	The state of the key. isExpired and expiresAt sit beside it
billingMode	deposit, arrears	A prepaid balance, or a subscription billed after use

See Key Status.

Query Values

Parameter	Values
timeWindow	A duration such as 30m, 1h, 4h, 24h, 7d, 30d. See Time Windows
from, to	Unix timestamps

Errors

A rejected /v2 request returns the standard error body:

{
  "code": "ERR_INVALID_PARAMETER",
  "message": "Invalid parameters",
  "details": [{ "field": "query.keywords", "message": "keywords is required" }],
  "errorId": "9d832e9b",
  "requestId": "715b9dc6-a0a3-4830-bf1e-bd518c7406c6"
}

Branch on the HTTP status first, then on code. Do not match on message. Parts of the x402 surface reject with a short { "error": "..." } body instead, with no code. Both shapes, and how to handle them together, are in Errors.

Code	HTTP	Means	Next step
ERR_UNAUTHORIZED	401	Missing, invalid or expired API key	Check the x-elfa-api-key header. See Authentication
ERR_FORBIDDEN	403	The key is valid but not entitled to this endpoint	Check your plan against Pricing
ERR_INSUFFICIENT_CREDITS	402	Not enough credits for the call. API-key surface only	Top up, or wait for the monthly reset
ERR_BAD_REQUEST	400	The request was malformed	Read message, fix and resend
ERR_INVALID_PARAMETER	400	A parameter is missing or invalid	Read details for the field
ERR_NOT_FOUND	404	No route, or the resource does not exist	Check the path against the API reference
ERR_RATE_LIMITED	429	Request rate exceeded	Back off and retry. See Rate Limits
ERR_RATE_LIMIT_EXCEEDED	429	Request rate exceeded, raised by a different limiter	Same handling. Branch on 429, not on which code you got
ERR_SERVICE_UNAVAILABLE	503	A dependency the endpoint needs declined or could not serve the request	Retry with backoff. A 503 is not an empty result
EXTERNAL_API_ERROR	upstream's status	An upstream service returned an error, so this is not always 5xx	Retry if the status is 5xx. Otherwise fix the request
EXTERNAL_API_REQUEST_FAILED	500	An upstream service did not respond	Retry with backoff
INTERNAL_SERVER_ERROR	500	Unhandled failure on our side	Retry once. If it persists, send us errorId and requestId

Not every code starts with ERR_. New codes can appear without a breaking change: treat an unrecognised code as its HTTP status implies.

Errors specific to one endpoint, such as a keyword mentions request with neither keywords nor accountName, are on its resource page under Errors.

402 on x402

On /x402/v2/* a 402 is not an error. It is the payment handshake: the body is an empty object {}, and the quote is in the base64-encoded PAYMENT-REQUIRED response header. Read the header and pay. See x402.

Which Failures to Retry

• Retry with backoff: 429, 503, and 500 (INTERNAL_SERVER_ERROR, EXTERNAL_API_REQUEST_FAILED, or EXTERNAL_API_ERROR with a 5xx status).
• Do not retry unchanged: 400, 401, 402, 403 and 404. The same request fails the same way. Change the request, the key or the balance first.

Reporting a Failure

Every response carries an x-request-id header. Send it to support with the errorId from the body when there is one, the endpoint and the time.

Related

• Overview for the conventions every v2 endpoint follows
• Errors for the error body shapes across the API
• v3 Enums and Errors