Skip to main content

​
Troubleshooting

​
API failures

  • 401 with missing_api_key:
    • send x-api-key
    • verify that SECAPI_API_KEY is set in the runtime making the request
  • 403:
    • confirm the key belongs to the expected organization and plan
    • confirm the endpoint is available for your plan
  • 429:
    • inspect secapi-meter-class, secapi-plan-key, and secapi-quota-limit
    • verify GET /v1/limits

​
MCP failures

  • authorization-server discovery returns 503:
    • retry after a short delay
    • use API-key authentication for REST requests while OAuth metadata is unavailable
  • tools/call returns Unknown tool:
    • re-run tools/list and use the exact published tool name
  • a tool call succeeds but lacks useful context:
    • capture the Request-Id
    • fetch the equivalent REST route for comparison

​
Billing failures

  • checkout fails:
    • verify GET /v1/billing
    • confirm the plan is checkoutEnabled
  • billing portal fails:
    • confirm the org has a Stripe customer
    • retry from an authenticated account with billing access
  • entitlement mismatch:
    • inspect /v1/billing and /v1/limits
    • include Request-Id when contacting support

​
Search failures

  • wrong filing in top result:
    • retry with a narrower issuer identifier, form type, or date range
    • include the query, expected filing, actual filing, and Request-Id in the support report
  • relevant section missing:
    • verify the filing exists through /v1/filings/latest or /v1/filings/{accession_number}
    • include the accession number, section key, and Request-Id

​
Data freshness

  • latest filing looks stale:
    • compare the SEC acceptance timestamp with the response freshness metadata
    • check https://api.secapi.ai/readyz
    • include the issuer, form, SEC accession if known, and Request-Id
  • normalized data differs from the filing:
    • keep the provenance, materialization, and trace fields from the response
    • include the source filing URL and the field that looks incorrect