SDK reliability

Use the SDK retry policy to absorb a short-lived read failure, not to hide a request, account, or data problem. Let one layer own retries: when your job runner, gateway, or application already retries, disable SDK retries there to avoid multiplying attempts during an outage. The JavaScript and Python SDKs retry eligible transient read failures. POST, PUT, PATCH, and DELETE are not retried for transient failures by default. A 429 is retried for any method when retries are enabled unless the API marks the response non-retryable; that does not make replaying a write safe.

Default retry boundary

Behavior	Default
Automatically retried methods	`GET`, `HEAD`, `OPTIONS`
Retryable failures	Network failures and HTTP `408`, `502`, `503`, `504` when the response is retryable; HTTP `429` unless the response is marked non-retryable
Not retried	HTTP `400`, `401`, `403`, `404`, `422`, and responses marked non-retryable
Retry count	Up to 3 retries
Backoff	Jittered exponential delay, starting at `200ms` and capped at `5s`
Retry budget	`30s`
Circuit breaker	Opens after 5 terminal retryable failures and cools down for `60s`

When the service provides Retry-After, the SDK uses it. When an intermediary removes that header, the SDK can also read structured retry timing in the API error payload.

Keep write retries explicit

Do not opt a write into retries unless your application can safely repeat the logical operation. Use an idempotency key where the endpoint supports one, keep it stable for that operation, and ensure no outer retry layer will create a second replay.

const client = new SecApiClient({
  apiKey: process.env.SECAPI_API_KEY,
  retry: false,
})

await client.callMcpTool(
  "entities.resolve",
  { ticker: "AAPL" },
  { retry: { enabled: true } },
)

MCP tool calls use POST. Opt in only for a read-only tool or an operation your application has made idempotent. For a 429, inspect the response’s retry guidance before deciding whether to replay a call.

Set retry ownership and deadlines

Disable SDK retries when another layer already owns backoff. Keep an application deadline around the whole user or worker operation; a retry budget controls the SDK attempt sequence, not the rest of your work.

const client = new SecApiClient({
  apiKey: process.env.SECAPI_API_KEY,
  retry: false,
})

import os

from secapi_client import SecApiClient

client = SecApiClient(
    api_key=os.environ["SECAPI_API_KEY"],
    retry=False,
    timeout=10,
)

The Python SDK uses a 30s per-request socket timeout by default. Choose a shorter timeout for latency-sensitive work, or ensure an outer transport layer provides the deadline you need. The JavaScript SDK applies its retry budget to the request attempt sequence.

Diagnose an SDK failure

API failures expose HTTP status, API error code, request ID, and response payload. Log the request ID with the operation that failed, then classify the response before retrying:

Correct 400 responses from the route or tool schema.
Repair the key or account context for 401, 402, and 403 responses.
On a retryable 429 or temporary service failure, follow the returned retry timing and keep concurrency bounded.
When the client circuit is open, wait for its cooldown instead of creating parallel client instances to bypass it.

The JavaScript SDK emits client_retry_attempt only when a telemetry capture token is configured. The Python SDK emits retry telemetry by default; set telemetry=False or telemetry={"enabled": False} to disable it. Read Troubleshooting for HTTP recovery decisions and MCP workflows before enabling retries for an MCP call.

Hosted MCP

Interactive tools

Default retry boundary

Keep write retries explicit

Set retry ownership and deadlines

Diagnose an SDK failure

​Default retry boundary

​Keep write retries explicit

​Set retry ownership and deadlines

​Diagnose an SDK failure

Default retry boundary

Keep write retries explicit

Set retry ownership and deadlines

Diagnose an SDK failure