> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Request diagnostics

> Capture a concise, secret-free record that makes an SEC API failure actionable

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.

```bash theme={null}
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.

```bash theme={null}
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.

## Redact before sharing

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](/troubleshooting) for the recovery path, [Error code catalog](/error-code-catalog) for known codes, or [API conventions](/api-conventions) for request behavior.