home / skills / jeremylongshore / claude-code-plugins-plus-skills / groq-common-errors

groq-common-errors skill

safe

/plugins/saas-packs/groq-pack/skills/groq-common-errors

This skill helps diagnose and fix Groq common errors by guiding you through identification, applying solutions, and verification of results.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill groq-common-errors

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.2 KB

---
name: groq-common-errors
description: |
  Diagnose and fix Groq common errors and exceptions.
  Use when encountering Groq errors, debugging failed requests,
  or troubleshooting integration issues.
  Trigger with phrases like "groq error", "fix groq",
  "groq not working", "debug groq".
allowed-tools: Read, Grep, Bash(curl:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Groq Common Errors

## Overview
Quick reference for the top 10 most common Groq errors and their solutions.

## Prerequisites
- Groq SDK installed
- API credentials configured
- Access to error logs

## Instructions

### Step 1: Identify the Error
Check error message and code in your logs or console.

### Step 2: Find Matching Error Below
Match your error to one of the documented cases.

### Step 3: Apply Solution
Follow the solution steps for your specific error.

## Output
- Identified error cause
- Applied fix
- Verified resolution

## Error Handling

### Authentication Failed
**Error Message:**
```
Authentication error: Invalid API key
```

**Cause:** API key is missing, expired, or invalid.

**Solution:**
```bash
# Verify API key is set
echo $GROQ_API_KEY
```

---

### Rate Limit Exceeded
**Error Message:**
```
Rate limit exceeded. Please retry after X seconds.
```

**Cause:** Too many requests in a short period.

**Solution:**
Implement exponential backoff. See `groq-rate-limits` skill.

---

### Network Timeout
**Error Message:**
```
Request timeout after 30000ms
```

**Cause:** Network connectivity or server latency issues.

**Solution:**
```typescript
// Increase timeout
const client = new Client({ timeout: 60000 });
```

## Examples

### Quick Diagnostic Commands
```bash
# Check Groq status
curl -s https://status.groq.com

# Verify API connectivity
curl -I https://api.groq.com

# Check local configuration
env | grep GROQ
```

### Escalation Path
1. Collect evidence with `groq-debug-bundle`
2. Check Groq status page
3. Contact support with request ID

## Resources
- [Groq Status Page](https://status.groq.com)
- [Groq Support](https://docs.groq.com/support)
- [Groq Error Codes](https://docs.groq.com/errors)

## Next Steps
For comprehensive debugging, see `groq-debug-bundle`.

Overview

This skill diagnoses and fixes common Groq errors and exceptions encountered during API integration and development. It provides quick identification of root causes, practical fixes, and verification steps to confirm resolution. Use it when Groq requests fail, responses are unexpected, or integrations behave intermittently.

How this skill works

The skill inspects error messages, HTTP status codes, and common log patterns to map incidents to known causes like authentication failures, rate limits, and network timeouts. For each matched error it suggests targeted fixes, commands to verify configuration, and pragmatic mitigation steps such as retries, timeouts, or credential rotation. It also outlines escalation steps when a problem requires vendor support.

When to use it

When you see explicit Groq error messages in logs or console
When requests start failing or timing out in production or development
While debugging failed API calls after deployment
When integrating Groq into CI/CD pipelines or serverless functions
During load testing where rate limits or throttling appear

Best practices

Verify API key presence and expiry before troubleshooting
Implement exponential backoff and jitter for retryable errors
Increase client timeout only after checking network and server status
Collect request IDs and full request/response traces before contacting support
Automate environment checks (env vars, connectivity, SDK version) in health probes

Example use cases

Fix an "Invalid API key" error by confirming environment variables and rotating credentials
Resolve "Rate limit exceeded" by adding exponential backoff and monitoring request volume
Address repeated "Request timeout" by raising client timeout and checking downstream latency
Run quick diagnostics: check Groq status page, curl API headers, and dump GROQ env vars
Prepare a debug bundle with request IDs and logs to escalate to Groq support

FAQ

What if my API key looks correct but I still get authentication errors?

Double-check the environment where the process runs (CI, container, or VM) for missing or overridden variables, ensure the key hasn’t expired, and try a fresh key rotation. Collect request IDs and timestamps if problem persists.

How should I handle rate limits during bursts?

Throttle requests client-side, use exponential backoff with jitter, batch operations where possible, and monitor usage to increase quotas if needed.

When should I increase client timeouts?

Only after confirming network connectivity and server health; increase timeouts incrementally and correlate with server-side latency metrics to avoid masking underlying issues.

What info should I provide when contacting Groq support?

Include request IDs, timestamps, full error messages, a debug bundle or trace, SDK version, and steps to reproduce. This speeds investigation and resolution.