Troubleshooting - SEC API for AI

Use this page when a REST, SDK, CLI, or hosted MCP request does not produce the result you expected. Start with the response, not a retry: record the HTTP status, error code, Request-Id, and traceparent when present. Those details separate a request problem from an account limit or a temporary service problem. Make one safe reproduction with the same credential context. This checks that the key reaches a machine-authenticated route without exposing it in a URL or request body.

curl -i -sS \
  -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/limits"

If this request does not succeed, resolve the credential or organization condition before investigating a filing, statement, SDK, or MCP workflow. Machine data requests use x-api-key; browser account actions use their documented signed-in browser flow.

Choose the next action from the response

Read the HTTP status and machine-readable code together. The code explains the particular stop; the status tells you whether to correct, wait, or change account state.

Response	What to do next
`400`, `invalid_query_parameter`, or `validation_error`	Compare the path, query, or body with the endpoint or tool schema. Correct the named field; do not retry unchanged input.
`401 missing_api_key`	Ensure the process making the request sends `x-api-key`.
`401 authentication_failed`	Replace or refresh the rejected credential through the appropriate account flow.
`401 missing_browser_session` or `403 human_auth_required`	Use a signed-in browser session for the browser-only action.
`402`, `billing_required`, or a budget code	Inspect billing and limits with the same credential, then resolve the stated account condition.
`403`	Confirm that the credential and plan are authorized for the resource or feature.
`429` or `rate_limit_exceeded`	Honor `Retry-After` when supplied, reduce concurrency, and retry only after that interval.
`5xx` or a transport failure	Use bounded backoff. Keep the response context if the failure repeats.

For code-specific recovery, see the error code catalog. A successful health check or unrelated endpoint does not prove that a particular issuer, filing, or derived data surface is available.

Resolve account, billing, and quota stops

Use the failing workload’s key for both checks. A different key can have different plan, billing, or quota state.

curl --fail-with-body -sS -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/billing"

curl --fail-with-body -sS -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/limits"

billing_budget_approval_required means a configured approval threshold stopped the request. billing_budget_hard_cap_exceeded means a configured hard cap stopped it. ai_query_quota_exceeded means the applicable AI-query allowance is exhausted. These are control signals, not transient failures: avoid a retry loop until the returned condition changes. See Agent billing, GET /v1/limits, and API keys, usage, and billing.

Investigate a result that is partial or surprising

A response can succeed at the HTTP layer while still carrying a route-specific limitation. Inspect returned capability, warning, provenance, period, freshness, and status-note fields where the route supplies them. Preserve the usable source evidence and show the limitation to your caller; do not silently substitute a different issuer, period, or data surface. For hosted MCP, confirm the client connects to https://api.secapi.ai/mcp, sends its configured API key for API-key authentication, and has refreshed its tool catalog. JSON-RPC -32004 indicates a tool execution-budget stop, -32005 an AI-query or MCP quota stop, and -32006 a tool-level protection stop. Narrow the request or wait for the applicable limit instead of issuing identical calls in parallel.

Escalate with a useful diagnostic

Include the method or tool name, a redacted request, UTC timestamp, HTTP status, error code, Request-Id, trace context, relevant response headers, and the outcome of GET /v1/limits with the same credential. For data results, include the returned filing or source identifiers. Exclude API keys, bearer tokens, cookies, and private payloads. Use Request diagnostics for the exact capture checklist.

​Choose the next action from the response

​Resolve account, billing, and quota stops

​Investigate a result that is partial or surprising

​Escalate with a useful diagnostic

Choose the next action from the response

Resolve account, billing, and quota stops

Investigate a result that is partial or surprising

Escalate with a useful diagnostic