Handle errors at every layer.
An HTTP success, a completed stream and a complete company report are different checks.
AI Financial Research API HTTP errors
| Status | Documented cause | Response handling |
|---|---|---|
| 400 | Invalid input or no_api_key | Read detail and code; correct input or account setup. |
| 401 | Missing or invalid token | Check the Token scheme and credential. |
| 403 | Missing AI-query entitlement or mcp_auth_error | Confirm the account’s access. |
| 429 | Quota or rate limit | Inspect X-Quota-* and Retry-After if returned. |
| 502 | mcp_connection_error | The data service was unreachable. |
AI Financial Research API stream errors
After the stream begins, errors arrive as events with detail and code. Documented codes are rate_limit, llm_unavailable, mcp_connection_error, mcp_auth_error, timeout and internal_error.
Financials, KYB and Watch API errors
Inspect non-success HTTP responses. General error examples contain detail, per-field validation arrays, or an access object with error_guard and message_guard. Do not apply the AI Financial Research API-specific error table as a complete contract for every endpoint.
Usage and retries
The public reference does not specify one universal rate limit or a fixed allowance for these APIs. AI Financial Research API query usage and underlying data usage are separate. Full company-report sections are individually metered. Confirm the enabled products and limits for your account.
Recommended implementation practice: retry transient failures with bounded backoff and respect Retry-After. Avoid blindly retrying watch mutations or an interrupted billable research request; reconcile the outcome first.
Documentation status
This guide was checked against the published reference on 16 September 2026. Request and response examples are illustrative and have not been run against a customer account. No webhook or watch subscription was created to produce this documentation.