When an LLM provider API key expires, an account balance runs out, or an account-level quota is exceeded, requests to that provider fail immediately across your applications. Coolhand monitors incoming request logs to catch these authentication and billing issues in real time, notify your team immediately, and confirm when service recovers.
How Coolhand detects credential and billing errors
Coolhand inspects the error messages returned on failed provider calls. Because providers do not format error responses identically—for instance, some providers return low balances under generic client error statuses rather than dedicated billing codes—Coolhand matches against the specific error signatures each provider emits.
Detected issues include:
- Expired or invalid API keys: Caught across providers such as OpenAI, Anthropic, Google Gemini, and Google Vertex AI when credentials have expired, been revoked, or entered incorrectly.
- Insufficient credit balances: Caught across providers such as Anthropic, OpenRouter, and DeepSeek when pre-paid credits or account balances are depleted.
- Exceeded quota limits: Caught on providers such as OpenAI when monthly spending caps or hard organizational usage limits are reached.
Excluded traffic and errors
Coolhand filters out traffic that should not trigger workspace-wide credential alerts:
- Local developer agent sessions: Captured sessions from tools like Claude Code or Claude Cowork run against an engineer's individual local credentials rather than your production application keys. These sessions are excluded so an expired personal token never triggers a false alert for your production integrations.
- Transient errors and rate limits: Temporary HTTP 429 rate limits and upstream 5xx provider outages represent capacity or availability blips rather than configuration or billing issues. They do not require key rotation or balance replenishment on your side and are monitored through separate reliability mechanisms.
Alert deduplication and email notifications
When a credential or billing failure strikes an active service, hundreds or thousands of calls can fail in seconds. To prevent overwhelming your inbox:
- Immediate notification: Coolhand sends an initial email notification to your workspace users as soon as the failure is identified. The email states which provider is affected, quotes the specific failure message returned by the provider, and provides guidance on what to check.
- One email per incident: Only one notification is sent for an active issue on a provider. Additional failed requests during the same outage are counted in the background rather than generating separate emails for each failure.
Dashboard banner and consolidated open alerts
While an alert remains open, a warning banner appears across your Coolhand dashboard. Clicking the banner opens a consolidated alerts view listing every active issue affecting your workspace:
- Provider credential and billing failures: Active API key and credit issues, including the timestamp when the first failure occurred and the running count of impacted requests.
- Model retirement notices: Advanced warnings about upcoming model deprecations and price changes affecting models your workspace actively uses.
- Provider-wide infrastructure outages: Outages verified across multiple accounts when an upstream provider experiences platform-wide downtime.
Automatic recovery and resolution confirmation
Once you rotate your expired API key, replenish your credit balance, or raise your spending limit, application traffic to the provider resumes.
Coolhand continuously monitors your incoming request stream. The moment requests to that provider succeed again:
- Coolhand automatically detects the recovery and closes the active alert.
- Workspace users receive a second confirmation email informing you that the provider is healthy and requests are completing successfully.
- Detection automatically re-arms, ensuring any future issue will trigger a prompt new notification.
What to do when you receive an alert
When you receive a credential or billing notification:
- Review the affected provider and error message: Open the email or the dashboard alert banner to confirm which provider failed and the exact reason reported.
- Update keys or replenish billing:
- Invalid or expired key: Generate a new API key in the provider's developer console. Update your secret manager, environment variables, or application configuration, and redeploy or restart the affected services.
- Low or empty balance: Log into the provider's billing portal and add funds or adjust auto-recharge settings.
- Quota exceeded: Check your account's monthly usage limits or request a quota tier upgrade from the provider.
- Verify recovery: Trigger a test request or monitor your service's outgoing traffic. As soon as clean requests reach Coolhand, the dashboard banner clears and Coolhand sends your recovery confirmation email.