Principle:Groq Groq python API Error Response Structure
| Knowledge Sources | |
|---|---|
| Domains | Error_Handling, Type_System |
| Last Updated | 2026-02-15 16:00 GMT |
Overview
Principle governing the structured representation of API error responses for programmatic error handling and debugging.
Description
When an API request fails, the response body contains structured error information that goes beyond HTTP status codes. API Error Response Structure defines a consistent schema for these error payloads, including: a human-readable message, a machine-readable type classification, an optional error code, the offending param name, and (for JSON schema validation errors) detailed schema path information. An optional Debug sub-structure provides token-level introspection (input/output token IDs and strings) when debug mode is enabled, which is valuable for diagnosing issues with structured output generation.
Usage
Apply this principle when implementing error handling in API clients. The structured error fields enable: branching on type for category-specific recovery logic; logging message for human review; inspecting param to identify which input caused the failure; and using schema_path details to fix JSON schema constraint violations in structured output scenarios.
Theoretical Basis
Structured API errors follow a layered information model:
# Abstract error structure
error = {
"message": "Human-readable description", # Always present
"type": "invalid_request_error", # Always present, machine-readable category
"code": "model_not_found", # Optional, specific error code
"param": "model", # Optional, which parameter failed
# Schema validation details (structured output errors):
"schema_code": "...",
"schema_kind": "...",
"schema_path": "...",
"schema_path_segments": ["...", "..."],
"failed_generation": "...", # The output that failed validation
# Debug mode only:
"debug": {
"input_token_ids": [...],
"input_tokens": [...],
"output_token_ids": [...],
"output_tokens": [...]
}
}
Error handling hierarchy:
- type -- Broad category for error recovery strategy
- code -- Specific cause for targeted handling
- param -- Input validation feedback
- schema_* -- JSON schema compliance details
- debug -- Token-level diagnostic data