Integration Health

Get a health overview of all your API integrations, with details on any keys that are degraded or unhealthy.

Request

GET /api/v1/integrations/health

Headers

Header	Value	Required
Authorization	Bearer {client_token}	Yes

Example Request

curl "https://spideriq.ai/api/v1/integrations/health" \
  -H "Authorization: Bearer $CLIENT_TOKEN"

Response

Success (200 OK)

{
  "success": true,
  "summary": {
    "total": 5,
    "healthy": 4,
    "degraded": 1,
    "unhealthy": 0
  },
  "integrations": [
    {
      "id": 42,
      "provider_name": "openrouter",
      "key_label": "Production OpenRouter",
      "health_status": "healthy",
      "consecutive_failures": 0,
      "last_used_at": "2026-02-26T15:00:00Z",
      "last_error": null
    },
    {
      "id": 43,
      "provider_name": "groq",
      "key_label": "Groq Free Tier",
      "health_status": "degraded",
      "consecutive_failures": 2,
      "last_used_at": "2026-02-26T14:55:00Z",
      "last_error": "Rate limit exceeded. Please retry after 60 seconds."
    },
    {
      "id": 44,
      "provider_name": "mistral",
      "key_label": "Mistral Production",
      "health_status": "healthy",
      "consecutive_failures": 0,
      "last_used_at": "2026-02-26T14:50:00Z",
      "last_error": null
    }
  ],
  "recommendations": [
    {
      "integration_id": 43,
      "provider_name": "groq",
      "issue": "Key is degraded with 2 consecutive failures",
      "action": "Monitor closely. Will be quarantined after 1 more failure."
    }
  ]
}

Health Status Definitions

Status	Meaning	Behavior
healthy	Working normally	Selected for requests
degraded	1-2 consecutive failures	Still selected, monitored
unhealthy	3+ consecutive failures	Quarantined, skipped

Health State Machine

                 ┌─────────────┐
                 │   HEALTHY   │
                 │  failures=0 │
                 └──────┬──────┘
                        │
            1 failure   │
                        ▼
                 ┌─────────────┐
                 │  DEGRADED   │◄────────┐
                 │ failures=1-2│         │
                 └──────┬──────┘         │ success
                        │                │
           3 failures   │                │
                        ▼                │
                 ┌─────────────┐         │
                 │  UNHEALTHY  │─────────┘
                 │ failures≥3  │
                 └─────────────┘
                        │
                        │ (quarantined)
                        │ Skipped from selection
                        │ Retried periodically
                        │
                        ▼
                 On success → HEALTHY

Recovery Process

Unhealthy keys are automatically:

1. Skipped from normal selection
2. Retried periodically (every 5 minutes)
3. Restored to healthy on first successful request

Common Issues and Solutions

Rate Limit Exceeded

{
  "last_error": "Rate limit exceeded"
}

Solution: Reduce request frequency or increase minute_limit at the provider.

Invalid API Key

{
  "last_error": "Invalid API key"
}

Solution: Verify the key in your provider's dashboard. Delete and recreate if rotated.

Insufficient Credits

{
  "last_error": "Insufficient balance"
}

Solution: Top up your account at the provider. SpiderGate will auto-recover.

Provider Outage

{
  "last_error": "Connection timeout"
}

Solution: Check provider status page. Key will auto-recover when provider is back.

Notes

• Health is tracked per-integration, not per-provider
• Multiple keys for the same provider can have different health states
• Degraded keys are still used (to allow recovery)
• Unhealthy keys still count toward your total integrations