Troubleshooting¶
Start with the machine-readable status, error_code, and audit_id. Avoid changing
multiple credentials, scopes, settings, and request fields at once.
Edge rejection (403, Cloudflare 1010)¶
A plain error code: 1010 response comes from Cloudflare before the request
reaches Argus. Production checks accept the Argus CLI, standard HTTPX and curl,
but Cloudflare rejects Python urllib's default User-Agent. Custom clients should
send an identifying header such as User-Agent: ArgusAgent/1.0. Keep the normal
OAuth or machine credential headers; a User-Agent does not authenticate a request.
An Argus authorization error instead has a structured error_code and audit_id.
Authentication (401)¶
| Error code | Check |
|---|---|
missing_credential |
X-Argus-API-Key, CLI ARGUS_MACHINE_API_KEY, or MCP api_key is actually supplied |
invalid_credential |
No whitespace/truncation; correct environment and service |
expired_credential / revoked_credential |
Rotate or reissue through the operator workflow |
institution_mismatch |
Request institution_id matches the credential |
caller_mismatch |
Request caller_id matches the credential |
tool_not_allowed |
Credential tool allowlist includes the registry tool id |
rate_limit_exceeded |
Back off until the credential window resets; do not rotate to evade limits |
Governance denial (400 or 403)¶
Current deployments do not block otherwise permitted facts because of
investment intent; confirm the server registry version and policy configuration.
- permission_denied: compare credential scopes with registry permissions.
- tenant_isolation_denied: remove cross-institution object references.
- license_denied: change source, purpose, field set, institution, or redistribution
intent; do not disable enforcement.
- output_policy_denied: Argus-originated advice or an invalid output category was
rejected. Verbatim, labeled source material remains eligible for fact output.
An unchanged retry will normally produce the same denial and a new audit record.
Request validation (422)¶
Fetch /openapi.json and compare the exact path schema. Common causes are naive
timestamps without timezone, wrong camel/snake casing, unknown fields, an invalid
US market session, reversed time ranges, empty required arrays, or a string where
an array is required.
Empty or incomplete result¶
Check known_time <= as_of, requested company/ticker identity, data period, evidence
gap classification, source ingestion state, connector run status, license-restricted
fields, and data_quality.issues. Use data_freshness_manifest,
evidence_gap_report, and field_catalog before assuming the source has no data.
The production data_freshness_manifest currently derives metadata from persisted
filings. Use dataset: regulatory_filings (or filing_disclosure_facts), the actual
filing source id (for example sec_edgar_filings), the canonical company id
(for example cik:0000320193), and an available field such as revenue or
filing.fragment. All four must match records in your institution. A market-data
example, unknown ticker, different source, or absent field returns a typed empty
result; it never substitutes another company's filings. The ingestion interval
uses retrieval timestamps, while known_time retains the source publication time.
Connector validation failure¶
Run connector validate, then fix the first concrete issue: unsupported provider,
disabled source, missing license id, missing policy, empty allowed uses, absent or
placeholder provider secret, or an invalid local file path. A dry_run still
requires valid authentication and licensing.
Service unready (503)¶
Read /health/ready and run the role-specific container health command. Typical
causes are PostgreSQL connectivity or migration-head mismatch, Redis failure,
object-storage access, missing Celery worker ping, stale Beat heartbeat, API
loopback failure, or MCP initialization/tool-list failure.
CLI runs locally by mistake¶
Run argus auth status, then argus auth login if needed. A stored OAuth
credential or ARGUS_ACCESS_TOKEN automatically selects
https://api.argusfa.com. Machine clients can set that ARGUS_BASE_URL or pass
--base-url. Do not use --local in a customer environment.
What to collect for escalation¶
Provide UTC timestamp, interface, tool id, HTTP status/CLI exit code, error_code,
audit_id, task/run id if present, requested as_of, and the relevant readiness
dependency. Redact API keys, authorization headers, provider secrets, full filing
contents, and restricted fields.