Docs / Page

Error Codes & Troubleshooting

Every error response includes a machine-readable code field that agents can parse programmatically, and a human-readable message for developers. Error responses never consume credits.

Error Reference

401API_KEY_REQUIRED

When

No X-API-Key header present

Next Action

Generate a key at agentii.ai/api-keys. Sign in first if you have not created an account.

Example Response

{"error":{"code":"API_KEY_REQUIRED","message":"A valid API key is required."}}

401INVALID_API_KEY

When

Key is revoked, expired, or never existed

Next Action

Generate a new key at agentii.ai/api-keys. Revoked keys cannot be reactivated.

Example Response

{"error":{"code":"INVALID_API_KEY","message":"Invalid or inactive API key."}}

403INSUFFICIENT_SCOPE

When

Key lacks the required access tier for this endpoint

Next Action

Request an agent_read key at agentii.ai/api-keys. Knowledge Store endpoints require agent_read or higher.

Example Response

{"error":{"code":"INSUFFICIENT_SCOPE","message":"...requires access tier agent_read.","details":{"required_scope":"agent_read","current_scope":"developer"}}}

429RATE_LIMIT_EXCEEDED

When

Per-minute burst limit reached

Next Action

Wait for the Retry-After duration. Consider upgrading your plan for a higher rate limit.

Example Response

{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"...retry in 12 seconds.","details":{"retry_after":12}}}

402CREDITS_EXHAUSTED

When

Monthly credit allowance depleted

Next Action

Purchase extra credits at $0.005/credit or upgrade to a higher plan tier at agentii.ai/account/billing.

Example Response

{"error":{"code":"CREDITS_EXHAUSTED","message":"Monthly credit allowance exhausted."},"upgrade_url":"https://agentii.ai/account/billing"}

503DATA_NOT_AVAILABLE

When

Backing data tables not yet populated (P2 endpoints)

Next Action

Check /v1/list_coverage for availability status. P2 endpoints activate when pipeline populates their backing tables.

Example Response

{"error":{"code":"DATA_NOT_AVAILABLE","message":"...not yet available.","details":{"coverage_url":"/v1/list_coverage"}}}

404NO_PAGE_DATA

When

Filing has no page-level silver data (10-K/10-Q — use structured endpoint)

Next Action

Use get_company_financials/{ticker} for structured financial statements, or search_xbrl_facts for granular XBRL data. 10-K and 10-Q filings do not have page-level silver data.

Example Response

{"error":{"code":"NO_PAGE_DATA","message":"No page data for 10-K filing.","details":{"suggested_endpoint":"/v1/get_company_financials/{ticker}"}}}

Error Response Format

All errors follow a consistent envelope:

{
  "error": {
    "code": "ERROR_CODE",        // Machine-readable — agents parse this
    "message": "Human description",  // Developer-facing explanation
    "details": {                  // Optional — contextual guidance
      "coverage_url": "/v1/list_coverage",
      "suggested_endpoint": "/v1/get_company_financials/{ticker}",
      "required_scope": "agent_read",
      "current_scope": "developer",
      "retry_after": 12
    }
  }
}

Agent Self-Documentation

The NO_PAGE_DATA error is a self-documentation mechanism. Its suggested_endpoint field tells agents exactly which endpoint to call instead. Agents implementing the retrieval decision tree can parse this field programmatically to auto-redirect — no manual intervention required.