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

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:

   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:

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

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.