Send a small Groq chat-completion request with its official Python client. You will keep the key in the environment, print observed usage and deliberately reject an invalid model without hiding the error.

What you'll build

The script is a diagnostic baseline: one request, a visible response and an explicit exit when something fails. It does not start a server, open a conversation loop or automatically try another provider. Keep it after integrating the API into a larger application so you can isolate account access from application logic.

Groq’s native client follows the platform’s Chat Completions interface and exposes status errors for unsuccessful requests. We use that client directly rather than add an abstraction layer to the first example. Official documentation.

Prerequisites

Complete the Groq API key walkthrough and check the selected project. Have a current Python environment and a test prompt that contains no private data.

This script selects openai/gpt-oss-20b from the current hosted model catalog. The publisher namespace is part of the identifier; the credential and endpoint still belong to Groq. Confirm project permissions before running it. Official documentation.

A valid key and a listed model do not establish unlimited capacity. Review Groq limits if several developers or workers share the organization.

Install SDK

python -m pip install --upgrade groq

Install into the environment that runs the script. The official client supports timeout and retry configuration; this diagnostic example disables automatic retries so its first failure remains visible. Official documentation.

Record the installed package version with your application. If another environment behaves differently, compare that version and the model configuration before rewriting the prompt.

Full script

import argparse
import json
import os
import sys
from groq import Groq, APIStatusError, APIConnectionError

parser = argparse.ArgumentParser()
parser.add_argument("--wrong-model", action="store_true")
args = parser.parse_args()
key = os.environ.get("GROQ_API_KEY")
if not key:
    raise SystemExit("Set GROQ_API_KEY in this process environment.")

model = "aiapihub-deliberately-invalid-model" if args.wrong_model else os.environ.get("GROQ_MODEL", "openai/gpt-oss-20b")
client = Groq(api_key=key, timeout=30.0, max_retries=0)
try:
    result = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": "Describe a useful text-classification task in one sentence."}],
        max_completion_tokens=256,
    )
except APIStatusError as exc:
    print("HTTP status:", exc.status_code)
    print(exc.response.text.replace(key, "[redacted]"))
    sys.exit(1)
except APIConnectionError:
    raise SystemExit("The request did not complete. Check connection and timeout.")
print("Groq response received.")
print(result.choices[0].message.content or "")
print("Usage:")
print(json.dumps(result.usage.model_dump() if result.usage else {}, indent=2))

Save the script as groq_first.py, set the key in the process environment and run it. GROQ_MODEL can select another documented identifier without editing the source.

python groq_first.py

The output limit in the code is a request setting for this example, not the provider’s published maximum. Adjust it for your test, then use returned usage to understand the work that actually occurred.

Expected output

On success, the program prints this literal banner, followed by generated text and the observed usage object:

Groq response received.

Generated content and usage are not fixed. Inspect the real output from your run; this tutorial does not present an invented successful API transcript. An absent answer should be diagnosed from the completion state and response rather than silently replaced with a made-up success message.

One deliberate error and its fix

python groq_first.py --wrong-model

The flag substitutes an intentionally nonexistent identifier while retaining the same credential and endpoint. The program prints the actual HTTP status and redacted response, then exits unsuccessfully. Restore the documented identifier to fix this deliberate failure.

AI API Hub reproduced this error with an authenticated REST request to POST https://api.groq.com/openai/v1/chat/completions on September 12, 2026, between 15:36 and 15:37 UTC. These are the recorded status and diagnostic fields; no valid-model inference or successful fallback was requested:

HTTP 404
error.code: model_not_found
error.type: invalid_request_error
error.message: The model `aiapihub-deliberately-invalid-model` does not exist or you do not have access to it.

An invalid model and a model blocked by project policy can produce different diagnostics. Read the returned error before concluding that the credential is wrong. Official documentation.

Replace the rejected model identifier with one currently available to your project, then run the normal script separately. Keep the observed status and diagnostic with the exact rejected identifier. This gives you a repeatable check that the error path preserves useful evidence.

What this request costs

Interactive tool

Estimate your API costs

Your text and estimates stay in this browser. No API requests are sent to model providers.

Loading verified model records…

Enter the script’s observed usage rather than assuming the requested output cap was fully consumed. The estimate covers supported token charges; check the official source before adding tool-assisted or media operations.

Next steps

Replace the prompt with a representative task and write down what a correct result must contain. Add schema checks or tool execution only after the baseline is repeatable. For a deployment, choose an overall deadline and shared retry budget.

Continue to the Groq models guide for alternatives and Groq errors for a diagnostic workflow. Keep secrets and unrelated account details out of saved examples.

Use the AI API cost calculator to turn the model and workload you are considering into an estimate.

Last verified · Source ↗

Frequently asked questions

Why use the Groq package here?
It is the provider’s official Python client and keeps the baseline close to its documented interface. Official documentation.
Can I choose another model?
Yes. Set GROQ_MODEL to a currently documented, permitted identifier and rerun the same saved task.
Why disable retries in the example?
To make the first rejection visible during diagnosis. Add a bounded production retry policy after deciding which failures are retryable.
What should successful output contain?
The literal success banner, generated message content and the returned usage object. The message itself is variable.
Does the deliberate-error mode run a second successful request?
No. It submits only the intentionally invalid identifier, prints the failure and exits. Run the normal mode separately after correcting the configuration.

Sources

Last verified · Source ↗