Groq error codes worth branching on: 498 flex-capacity, 499 cancelled, 422 semantic

TL;DR: 498 means the Flex tier is at capacity: wait and retry later, or switch to a standard tier. Official docs (API Error Codes and Responses): documents Groq's non-standard error codes that surprise agents: 498 custom (Flex tier at capacity, request won't be processed), 499 custom (request cancelled by the caller, shown in logs), and 422 (well-formed request with semantic errors, sometimes model hallucination in structured output).

Groq error codes worth branching on: 498 flex-capacity, 499 cancelled, 422 semantic

Fix

1. means the Flex tier is at capacity: wait and retry later, or switch to a standard tier. Expected: the request routes instead of erroring.

2. usually means the request data itself was bad or the model produced malformed structured output: verify the payload and retry once before blaming the API. Expected: this specific failure stops.

Details

Error bodies always follow {error: {message, type}}. You are not charged for server error codes. ## What to do Branch on Groq error codes instead of treating everything as a retryable 5xx. Parse the error object as error.message (human description) + error.type (category like invalidrequesterror) and log both; the message is stable enough to match on. Server-side 500/502/503 are the only ones worth plain retries.

When to use

You hit exactly this: Groq error codes worth branching on: 498 flex-capacity, 499 cancelled, 422 semantic in Groq error codes worth branching on.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Groq error codes worth branching on.

Root cause

499 in your logs means YOUR client cancelled the request, not Groq, so look at timeouts and cancellations on your side.

Edge cases

• Official docs (API Error Codes and Responses): documents Groq's non-standard error codes that surprise agents: 498 custom (Flex tier at capacity, request won't be processed), 499 custom (request cancelled by the caller, shown in logs), and 422 (well-formed request with semantic errors, sometimes model hallucination in structured output).

Official docs (API Error Codes and Responses): documents Groq's non-standard error codes that surprise agents: 498 custom (Flex tier at capacity, request won't be processed), 499 custom (request cancelled by the caller, shown in logs), and 422 (well-formed request with semantic errors, sometimes model hallucination in structured output). Error bodies always follow {error: {message, type}}. You are not charged for server error codes.

Verified answer: Branch on Groq error codes instead of treating everything as a retryable 5xx. 498 means the Flex tier is at capacity: wait and retry later, or switch to a standard tier. 499 in your logs means YOUR client cancelled the request, not Groq, so look at timeouts and cancellations on your side. 422 usually means the request data itself was bad or the model produced malformed structured output: verify the payload and retry once before blaming the API. Parse the error object as error.message (human description) + error.type (category like invalidrequesterror) and log both; the message is stable enough to match on. Server-side 500/502/503 are the only ones worth plain retries.

Source: https://console.groq.com/docs/errors