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:

{
  "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

Capture the failing status and body. Read the raw error response — the HTTP status plus the code/type fields determine the whole diagnosis path.

Confirm the key works before assuming anything deeper:

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'

Confirm the model still exists. Many 400s are deprecated model IDs — list the live models and Grep your codebase for any stale ID:
```
curl -s https://api.groq.com/openai/v1/models \
  -H "Authorization: Bearer $GROQ_API_KEY" | jq '.data[].id' | sort
```
Map the status to a fix using the table below, then drill into references/error-reference.md for the exact error string, causes, and copy-paste fix.
For SDK integrations, branch on the typed exception classes — see 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.

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:

# 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.
Typed SDK exception branching (TypeScript + Python): references/sdk-error-handling.md.

Resources

Groq Error Codes
Groq Rate Limits
Groq Model Deprecations
Groq Status Page
Full per-status reference: references/error-reference.md
SDK error handling + escalation path: references/sdk-error-handling.md
For comprehensive debugging, see the groq-debug-bundle skill.