---
name: jeremylongshore/groq-common-errors
source: https://app.decimal.ai/s/jeremylongshore-groq-common-errors@1/SKILL.md
source_sha256: 2150fe83553a
---

# 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.