groq-common-errors

name	groq-common-errors
description	Diagnose and fix Groq API errors with real error codes and solutions. 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", "groq 429".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.11.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","groq","debugging"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

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: