groq-sdk

Postconditions — what we check

• create · api-error

  error
  WhenAny API or network failure: rate limit (429), auth error (401), bad request (400), server error (5xx), network timeout, or connection failure
  ThrowsGroq.APIError subclass: RateLimitError (429), AuthenticationError (401), BadRequestError (400), InternalServerError (5xx), APIConnectionError (network), APIConnectionTimeoutError (timeout)
  Required handlingCaller MUST wrap in try-catch. The SDK retries automatically (default maxRetries=2) but throws on final failure. Uncaught errors will crash the caller or produce unhandled promise rejections in production. Minimum handling: try { const completion = await groq.chat.completions.create({ ... }); } catch (err) { if (err instanceof Groq.RateLimitError) { /* backoff */ } else if (err instanceof Groq.APIError) { /* log and surface */ } else throw err; } For streaming (stream: true), the try-catch must wrap the entire for-await loop as errors can be thrown mid-stream.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• create · api-error

  error
  WhenNetwork failure, invalid file format, unsupported model, or API error
  ThrowsGroq.APIError or subclass (BadRequestError for invalid format/model, InternalServerError for server-side failures, APIConnectionError for network)
  Required handlingCaller MUST wrap in try-catch. File format errors (e.g., wrong extension, corrupt audio) and network errors both surface as thrown exceptions. Log error with file metadata for debugging.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• create · api-error

  error
  WhenNetwork failure, invalid file, unsupported model, or API error
  ThrowsGroq.APIError or subclass
  Required handlingCaller MUST wrap in try-catch. Same error surface as transcriptions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• create · api-error

  error
  WhenNetwork failure, invalid voice/model, or API error
  ThrowsGroq.APIError or subclass
  Required handlingCaller MUST wrap in try-catch. TTS failures leave the caller with no audio response — this should be surfaced, not swallowed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• create · api-error

  error
  WhenNetwork failure, rate limit, or API error
  ThrowsGroq.APIError or subclass (RateLimitError most common under load)
  Required handlingCaller MUST wrap in try-catch. Embedding failures in batch processing pipelines should be caught per-item to avoid aborting the whole batch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• create · groq-batches-no-try-catch

  error
  Whengroq.batches.create() called without try-catch
  ThrowsGroq.APIError subclasses: BadRequestError (400, invalid file_id or params), AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network)
  Required handlingCaller MUST wrap in try-catch. File validation failures (malformed JSONL, wrong content-type, non-existent file_id) throw immediately. Network errors also throw. Unhandled rejections crash the caller.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• create · groq-batches-result-not-checked

  warning
  WhenBatch submitted but result status not polled or individual request_counts.failed not checked after completion
  ThrowsDoes not throw — errors are returned as per-item error objects in the JSONL results file. The batch itself may "complete" with individual failures silently buried in the results file.
  Required handlingAfter batch completion, caller MUST retrieve results via files.content() and parse each line. Each line has a response.status_code — non-200 lines are individual failures that MUST be handled. Checking only that the batch completed (status == "completed") is insufficient.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[5]
• create · groq-files-upload-no-try-catch

  error
  Whengroq.files.create() called without try-catch
  ThrowsGroq.APIError subclasses: BadRequestError (400, invalid file format or JSONL content errors), AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network)
  Required handlingCaller MUST wrap in try-catch. JSONL validation errors (malformed lines, wrong format) and network errors both throw. File creation returns a FileCreateResponse with an id field — callers must capture this id for subsequent batches.create() calls.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• create · groq-files-id-not-used

  warning
  Whenfiles.create() result file id not stored or passed to batches.create()
  ThrowsDoes not throw at files.create() time. Downstream batches.create() will throw BadRequestError (400) with an invalid file_id.
  Required handlingCaller MUST capture the returned FileCreateResponse.id and use it as the input_file_id in the subsequent batches.create() call. Discarding the return value makes the upload useless and the batch will fail.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• cancel · groq-batches-cancel-no-try-catch

  warning
  Whengroq.batches.cancel() called without try-catch
  ThrowsGroq.APIError subclasses: NotFoundError (404, invalid or expired batchID), AuthenticationError (401), InternalServerError (5xx), APIConnectionError
  Required handlingCaller MUST wrap in try-catch. NotFoundError is common when the batch has already completed or expired. Cancellation during webhook/callback flows should handle the "already completed" case explicitly.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• retrieve · groq-batches-retrieve-no-try-catch

  error
  Whengroq.batches.retrieve() called without try-catch
  ThrowsGroq.APIError subclasses: NotFoundError (404, invalid or expired batchID), AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network)
  Required handlingCaller MUST wrap in try-catch. Poll loops are the dominant usage pattern — unhandled NotFoundError on a batchID that has expired (Groq batches expire after 7 days per docs) crashes the polling worker. RateLimitError on a tight polling loop is also common; back off using err.headers['retry-after'].
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• list · groq-batches-list-no-try-catch

  error
  Whengroq.batches.list() called without try-catch
  ThrowsGroq.APIError subclasses: AuthenticationError (401, missing/invalid API key), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network), APIConnectionTimeoutError (timeout)
  Required handlingCaller MUST wrap in try-catch. Unhandled network errors crash the listing job (common in scheduled cost-reporting workers).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• list · groq-files-list-no-try-catch

  error
  Whengroq.files.list() called without try-catch
  ThrowsGroq.APIError subclasses: AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network)
  Required handlingCaller MUST wrap in try-catch. Listing failures in cleanup/audit cron jobs should be surfaced rather than swallowed — silent failures leave orphaned batch files accumulating against the 100MB-per-file storage limit.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• delete · groq-files-delete-no-try-catch

  error
  Whengroq.files.delete() called without try-catch
  ThrowsGroq.APIError subclasses: NotFoundError (404, fileID already deleted or never existed), AuthenticationError (401), ConflictError (409, file is referenced by an active batch), InternalServerError (5xx), APIConnectionError
  Required handlingCaller MUST wrap in try-catch. NotFoundError on idempotent delete loops (deleting a file already removed by an earlier cleanup) is common — handle it explicitly as a success-equivalent rather than swallowing all errors. ConflictError indicates the file is still in use by a batch — block deletion until batches.list() confirms no active batch references it.
  costlowin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[5][1]
• content · groq-files-content-no-try-catch

  error
  Whengroq.files.content() called without try-catch
  ThrowsGroq.APIError subclasses: NotFoundError (404, invalid fileID), AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network), APIConnectionTimeoutError (timeout on large batch-output downloads)
  Required handlingCaller MUST wrap in try-catch. Batch-output files can be large (up to 100MB) and downloads time out under poor network conditions — wrap the entire .content() call AND the subsequent .text()/.body stream consumption in the same try-catch since stream errors can also throw mid-read. Failure to retrieve batch output means the batch results are LOST until the file expires, even though the batch itself completed successfully.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[5][1]
• content · groq-files-content-response-not-consumed

  warning
  Whenfiles.content() Response not consumed via .text(), .json(), or .body stream — return value discarded or only checked for .ok / .status
  ThrowsDoes not throw. The Response body is left unconsumed, leading to memory leaks and (in some fetch implementations) keeping the connection open until the abort signal fires.
  Required handlingCaller MUST consume the Response body (await .text(), .json(), or read .body as a stream). Discarding the return value of files.content() means the batch-output JSONL never reaches the caller — silent data loss. Even on error paths (response.ok === false), call .text() to read the error body before discarding.
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[6][5]
• info · groq-files-info-no-try-catch

  error
  Whengroq.files.info() called without try-catch
  ThrowsGroq.APIError subclasses: NotFoundError (404, invalid fileID), AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network)
  Required handlingCaller MUST wrap in try-catch. NotFoundError on a fileID that the upstream code thought existed indicates a race condition (file deleted between create and info call) — surface as a user-visible error rather than swallowing.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• retrieve · groq-models-retrieve-no-try-catch

  error
  Whengroq.models.retrieve() called without try-catch
  ThrowsGroq.APIError subclasses: NotFoundError (404, model id does not exist or has been deprecated by Groq), AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError
  Required handlingCaller MUST wrap in try-catch. Groq deprecates models on a rolling basis — NotFoundError on a hardcoded model id is the dominant production failure mode for long-lived deployments. Handle it as "model unavailable, fall back to default" rather than crashing.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][8][1]
• list · groq-models-list-no-try-catch

  error
  Whengroq.models.list() called without try-catch
  ThrowsGroq.APIError subclasses: AuthenticationError (401), RateLimitError (429), InternalServerError (5xx), APIConnectionError (network)
  Required handlingCaller MUST wrap in try-catch. Models-list failures at startup should fall back to a hardcoded known-good list rather than crashing the app — the deployment must still serve traffic even if the discovery call temporarily fails.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][1]
• delete · groq-models-delete-no-try-catch

  error
  Whengroq.models.delete() called without try-catch
  ThrowsGroq.APIError subclasses: NotFoundError (404, model id does not exist or already deleted), PermissionDeniedError (403, attempting to delete a Groq-owned built-in model), AuthenticationError (401), InternalServerError (5xx), APIConnectionError (network)
  Required handlingCaller MUST wrap in try-catch. PermissionDeniedError on a built-in model id (e.g. attempting to delete "llama-3.3-70b-versatile") indicates a bug in the calling code — surface as a hard error, do NOT silently swallow. NotFoundError on idempotent delete loops is success-equivalent.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[7][1]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]console.groq.com/docs/errorshttps://console.groq.com/docs/errors
2. [2]console.groq.com/docs/speech-texthttps://console.groq.com/docs/speech-text
3. [3]console.groq.com/docs/text-speechhttps://console.groq.com/docs/text-speech
4. [4]console.groq.com/docs/openaihttps://console.groq.com/docs/openai
5. [5]console.groq.com/docs/batchhttps://console.groq.com/docs/batch
6. [6]developer.mozilla.org/en-US/docshttps://developer.mozilla.org/en-US/docs/Web/API/Response
7. [7]console.groq.com/docs/modelshttps://console.groq.com/docs/models
8. [8]console.groq.com/docs/deprecationshttps://console.groq.com/docs/deprecations