groq-common-errors

# Groq Common Errors ## Overview Comprehensive reference for Groq API error codes, their root causes, and proven fixes. Groq returns standard HTTP status codes with structured error bodies and rate-limit headers. This skill walks the diagnosis from raw error string to fix, then hands off to the full per-status reference for depth. Every Groq error body follows one shape — read the `code` and `type` first: ```json { "error": { "message": "Rate limit reached for model `llama-3.3-70b-versatile`...", "type": "tokens", "code": "rate_limit_exceeded" } } ``` ## Prerequisites - `GROQ_API_KEY` exported in the environment (keys start with `gsk_`). - `curl` and `jq` available for the diagnostic probes below. - For SDK-level handling: `groq-sdk` (TypeScript) or `groq` (Python) installed. ## Instructions 1. **Capture the failing status and body.** Read the raw error response — the HTTP status plus the `code`/`type` fields determine the whole diagnosis path. 2. **Confirm the key works** before assuming anything deeper: ```bash set -euo pipefail # Verify API key is valid — expect a model count, not an auth error curl -s https://api.groq.com/openai/v1/models \ -H "Authorization: Bearer $GROQ_API_KEY" | jq '.data | length' ``` 3. **Confirm the model still exists.** Many 400s are deprecated model IDs — list the live models and Grep your codebase for any stale ID: ```bash curl -s https://api.groq.com/openai/v1/models \ -H "Authorization: Bearer $GROQ_API_KEY" | jq '.data[].id' | sort ``` 4. **Map the status to a fix** using the table below, then drill into [references/error-reference.md](references/error-reference.md) for the exact error string, causes, and copy-paste fix. 5. **For SDK integrations**, branch on the typed exception classes — see [references/sdk-error-handling.md](references/sdk-error-handling.md). ## Output A diagnosis that names the error class, the root cause, and the concrete fix — for example: "429 on TPM: token budget exhausted; add the single-retry `handleRateLimit` wrapper and honor `retry-after`," or "400: `mixtral-8x7b-32768` is deprecated; switch to `llama-3.3-70b-versatile`." When run against real code, the output is the edited call site plus a verification `curl` that returns `200`. ## Error Handling Map the HTTP status to its cause; full error strings, rate-limit headers, and fixes live in [references/error-reference.md](references/error-reference.md). | Status | Meaning | First move | |--------|---------|------------| | **401** | Invalid / missing key | Confirm `GROQ_API_KEY` starts with `gsk_`; test with `/models` | | **429** | RPM / TPM / RPD limit hit | Read `retry-after`; back off and single-retry | | **400** | Deprecated model or bad params | List live models; replace stale IDs | | **413** | Request over context window | Trim prompt (Llama models cap at 128K tokens) | | **500 / 503** | Groq-side outage or overload | Retry with backoff; fall back model; check status page | When the failure is transient (429/500/503), retry with backoff and honor `retry-after` rather than hammering. When it is structural (401/400/413), fix the request — retrying will not help. ## Examples Minimal end-to-end probe that isolates auth vs. model vs. payload problems: ```bash # A 200 here means key + model + payload are all valid; a non-200 status # tells you which layer failed. curl -s -o /dev/null -w "%{http_code}" \ https://api.groq.com/openai/v1/chat/completions \ -H "Authorization: Bearer $GROQ_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"llama-3.1-8b-instant","messages":[{"role":"user","content":"ping"}],"max_tokens":5}' ``` - **Rate-limit retry wrapper** (TypeScript, honors `retry-after`): see the 429 section of [references/error-reference.md](references/error-reference.md). - **Typed SDK exception branching** (TypeScript + Python): [references/sdk-error-handling.md](references/sdk-error-handling.md). ## Resources - [Groq Error Codes](https://console.groq.com/docs/errors) - [Groq Rate Limits](https://console.groq.com/docs/rate-limits) - [Groq Model Deprecations](https://console.groq.com/docs/deprecations) - [Groq Status Page](https://status.groq.com) - Full per-status reference: [references/error-reference.md](references/error-reference.md) - SDK error handling + escalation path: [references/sdk-error-handling.md](references/sdk-error-handling.md) - For comprehensive debugging, see the `groq-debug-bundle` skill.