Skip to content

Error Codes

DeepFabric uses standardized error codes to provide consistent, actionable feedback during dataset generation. Error codes appear in the TUI Events panel and help diagnose issues with sample failures.

Overview

Error codes follow the format DF-XNN:

  • DF: DeepFabric prefix
  • X: Category letter (R=Rate limit, A=Auth/API, N=Network, P=Parse, T=Tool, X=Unknown)
  • NN: Number within category

Errors are classified by severity:

  • Sample-level: Generation continues; the failed sample is skipped
  • Fatal: CLI exits immediately; requires configuration fix

TUI Display

During generation, errors appear in the Events panel with colored indicators:

X [42] DF-R01 Rate limit (RPM) - retry 3s
✓ Generated +2 samples
X [45] DF-P01 JSON parse error
✓ Generated +3 samples
  • Red X indicates an error with the error code and brief description
  • Green ✓ indicates successful sample generation
  • The number in brackets [42] is the sample index

Error Code Reference

Rate Limit Errors (DF-R0x)

Rate limit errors occur when the LLM provider throttles requests. These are typically retryable.

Code Message Severity Description
DF-R01 Rate limit (RPM) Sample Requests per minute limit exceeded. Provider is throttling requests.
DF-R02 Rate limit (daily) Sample Daily quota exhausted. Resets at midnight (provider timezone).
DF-R03 Rate limit (tokens) Sample Token per minute limit exceeded.
DF-R04 Rate limit Sample Generic rate limit error from provider.

Common causes:

  • Too many concurrent requests (reduce batch_size)
  • High request volume (add rate_limit configuration)
  • Free tier limits (upgrade API plan or switch providers)

Solutions:

data_engine:
  # Reduce concurrency
  batch_size: 1

  # Add rate limiting
  rate_limit:
    base_delay: 3.0
    max_delay: 120.0
    max_retries: 5

Auth/API Errors (DF-A0x)

Authentication and API configuration errors.

Code Message Severity Description
DF-A01 Auth failed Fatal Authentication failed. Check your API key environment variable.
DF-A02 Model not found Fatal The specified model does not exist or is not accessible.
DF-A03 API error Sample Generic API error from the provider.

Common causes:

  • Missing or invalid API key
  • Incorrect model name
  • API key lacks required permissions

Solutions:

# Ensure API key is set
export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=...
export ANTHROPIC_API_KEY=...

# Verify model name matches provider's naming
# OpenAI: gpt-4o, gpt-4o-mini
# Gemini: gemini-2.0-flash, gemini-1.5-pro
# Anthropic: claude-3-5-sonnet-20241022

Network Errors (DF-N0x)

Network and connectivity issues.

Code Message Severity Description
DF-N01 Network error Sample Connection failed. Check your internet connection.
DF-N02 Timeout Sample Request timed out waiting for provider response.
DF-N03 Service unavailable Sample Provider service temporarily unavailable (503/502).

Common causes:

  • Internet connectivity issues
  • Provider service outage
  • Firewall blocking requests
  • Request timeout too short

Solutions:

data_engine:
  # Increase request timeout
  request_timeout: 60  # seconds

  # Configure retries for transient failures
  rate_limit:
    max_retries: 5
    backoff_strategy: "exponential_jitter"

Parse Errors (DF-P0x)

Errors parsing or validating LLM responses.

Code Message Severity Description
DF-P01 JSON parse error Sample Failed to parse JSON from LLM response.
DF-P02 Schema validation Sample Response does not match expected schema structure.
DF-P03 Empty response Sample LLM returned an empty or whitespace-only response.
DF-P04 Malformed response Sample Response structure is malformed or incomplete.

Common causes:

  • LLM producing invalid JSON
  • Schema too strict for model capabilities
  • Temperature too high causing inconsistent outputs
  • Model context length exceeded

Solutions:

data_engine:
  # Lower temperature for more consistent outputs
  temperature: 0.5

  # Ensure sufficient token budget
  max_tokens: 2000

Tool Errors (DF-T0x)

Errors related to tool/function calling in agent mode.

Code Message Severity Description
DF-T01 Tool validation Sample Tool call format is invalid or missing required fields.
DF-T02 Tool limit exceeded Sample Sample exceeded maximum tool calls per query.
DF-T03 No tool execution Sample Agent mode requires at least one tool execution.

Common causes:

  • max_tools_per_query set too low
  • Tool schema incompatible with model
  • Model not capable of structured tool calling

Solutions:

data_engine:
  # Increase tool limit if needed
  max_tools_per_query: 5

  # Set to false to keep samples that exceed limit (truncated)
  max_tools_strict: false

  # Use a model with good tool calling support
  provider: "openai"
  model: "gpt-4o"

Unknown Errors (DF-X0x)

Uncategorized errors that don't match known patterns.

Code Message Severity Description
DF-X01 Unknown error Sample An unexpected error occurred.

Debugging unknown errors:

# Run with debug flag for full error details
deepfabric start config.yaml --debug

Provider-Specific Notes

Gemini

Gemini has stricter rate limits and schema requirements:

  • Uses RPM (requests per minute) and RPD (requests per day) limits
  • Daily quota resets at midnight Pacific time
  • Requires minItems/maxItems for arrays in schemas
  • Does not support additionalProperties in schemas

Recommended configuration:

data_engine:
  provider: "gemini"
  model: "gemini-2.0-flash"

  rate_limit:
    base_delay: 3.0
    max_delay: 120.0

OpenAI

OpenAI provides detailed rate limit headers and retry-after information:

  • Supports strict mode for schema validation
  • Good tool calling support across models
  • Provides x-ratelimit-* headers for capacity tracking

Anthropic

Anthropic uses a token bucket algorithm:

  • Separate limits for requests, input tokens, and output tokens
  • Provides anthropic-ratelimit-* headers
  • Good at following complex prompts

Ollama

Ollama runs locally with minimal rate limiting:

  • Rate limits unlikely unless resource-constrained
  • Connection errors usually mean server not running
  • Use ollama serve to start the server

Programmatic Access

Error codes can be accessed programmatically:

from deepfabric.error_codes import (
    classify_error,
    ALL_ERROR_CODES,
    DF_R01,
    ErrorCategory,
    ErrorSeverity,
)

# Classify an error
classified = classify_error(some_exception, provider="gemini")
print(classified.error_code.code)  # "DF-R01"
print(classified.error_code.short_message)  # "Rate limit (RPM)"
print(classified.to_event())  # "DF-R01 Rate limit (RPM) - retry 3s"

# Check error properties
if classified.error_code.severity == ErrorSeverity.FATAL:
    print("This error requires immediate attention")

# List all error codes
for code, error in ALL_ERROR_CODES.items():
    print(f"{code}: {error.description}")

Troubleshooting Workflow

  1. Check the Events panel for error codes during generation
  2. Look up the error code in this reference
  3. Apply recommended solutions from the relevant section
  4. Run with --debug if you need more details: 
    deepfabric start config.yaml --debug
  5. Check provider status if seeing persistent DF-N03 errors
  6. Review rate limit configuration if seeing DF-R0x errors frequently