Request diagnostics - SEC API for AI

Capture the failed response before changing a key, client, or retry policy. A status code by itself cannot distinguish malformed input, rejected authentication, a billing stop, rate limiting, or a temporary service failure. A small diagnostic record lets another operator reproduce the issue without receiving your secrets.

Preserve one inspectable response

Run one request with headers included, then store the output privately. -i exposes response headers such as Request-Id, traceparent, and Retry-After when the API returns them.

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

Do not paste the command with its expanded key into a ticket, log, or screenshot.

Keep this minimum record

Capture	Why it matters
HTTP method and endpoint path	Identifies the operation without disclosing credentials.
UTC timestamp, HTTP status, and error `code`	Places the event and identifies the recovery class.
Returned `message`, `hint`, and `docsUrl`	Preserves route-specific correction steps when supplied.
`Request-Id` and `traceparent`	Correlates the API request when present.
`Retry-After` plus relevant quota or billing headers	Shows whether a retry is appropriate and when it may start.
SDK, CLI, MCP client, or HTTP-library version	Makes client behavior reproducible.

For a body, keep a redacted copy. Include query parameters, response view, and pagination cursor when they affect the result. You may also send x-request-id to match an API call to your own logs; keep the returned Request-Id as the API-side identifier.

Classify before you retry

Response class	Safe next action
`400` or validation response	Correct the request using the route or tool schema.
`401` or `403`	Verify the credential context. API data requests use `x-api-key`; a dashboard bearer session is not a substitute.
`402`	Stop and resolve the billing, entitlement, or budget condition in the response.
`429`	Honor `Retry-After` when returned and reduce concurrency before a bounded retry.
`5xx` or transport failure	Use bounded backoff and keep the captured request context.

Do not turn a validation, authorization, billing, hard-cap, or quota response into a tight retry loop.

Verify the same account context

Check limits and billing with the same key used by the failing workload. This is especially useful after a 402 or 429 response.

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

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

For an MCP failure, record the client name and version, server URL, tool or method name, JSON-RPC error, error.data.code when supplied, and request identifier. For an SDK or CLI failure, add its version and the smallest redacted reproduction. Remove x-api-key, bearer tokens, cookies, and other credentials. Remove customer data, private holdings, unreleased text, and proprietary prompts unless a narrowed reproduction genuinely requires them. Keep the endpoint path, status, error code, request ID, and the smallest useful response excerpt. Continue with Troubleshooting for the recovery path, Error code catalog for known codes, or API conventions for request behavior.

​Preserve one inspectable response

​Keep this minimum record

​Classify before you retry

​Verify the same account context

​Redact before sharing

Preserve one inspectable response

Keep this minimum record

Classify before you retry

Verify the same account context

Redact before sharing